# Overview

A webhook is a way for MinChat to notify your server in real-time when a specific event occurs.

When webhooks are enabled in the [minchat dashboard](https://minchat.io/webhooks), your server will receive HTTP POST requests from minchat servers notifying you about events that happen in your application between your users.

## Webhook Events

MinChat supports the following webhook events

### Message Sent

Is triggered when a message is sent by a user.

{% code title="payload" %}

```javascript
{
   "sent_by":{
      "id":"639575b2c280a7001e892906",
      "name":"Samantha Smith",
      "username":"samantha",
      "avatar": "urltoavatar.com/mercyavatar.jpg"
   },
   "sent_to":[
      {
         "id":"289575b9b280a7001e892956",
         "name":"Jackie",
         "username":"jackie_01",
         "avatar": "urltoavatar.com/mercyavatar.jpg"
      }
   ],
   "chat_id": "63d3e12d669fc928b3d78f80",
   "text":"Hello guys!",
   "file": {
        type: "image",
        url: "https://urltofile.com/image.jpeg",
        "name": "Assignment Project",
        "size": "2 MB",
    },
    "metadata": {}
    "chat_metadata": {}
}
```

{% endcode %}

<table><thead><tr><th width="167">Field</th><th width="148.66666666666666">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>sent_by</code></td><td><a href="../reference/user"><code>User</code></a></td><td>The user that sent the message</td></tr><tr><td><code>sent_to</code></td><td><a href="../reference/user"><code>User[]</code></a></td><td>An array of users that have received the message</td></tr><tr><td><code>text</code></td><td><code>string</code></td><td>The content of the message</td></tr><tr><td><code>file</code></td><td><a href="../reference/file"><code>File</code></a></td><td>A file attachment associated with this message</td></tr><tr><td><code>chat_id</code></td><td><code>string</code></td><td>The id of the conversation this message was sent to</td></tr><tr><td>metadata</td><td><code>json object</code></td><td>an optional key value pair for any additional message information.</td></tr><tr><td>chat_metadata</td><td><code>json object</code></td><td>an optional key value pair for any additional chat information.</td></tr></tbody></table>

### New Conversation

Is triggered when a new conversation is created

```javascript
{
    "id": "cmd5vwylc0006qfe97knky6vt",
    "title": "Group Chat",
    "participant_user_ids": [
        "cmd5vwyjr0003qfe9zuhmmvoz",
        "cmcjal25k0001lu9dj45zq4jy"
    ],
    "avatar": "https://urltofile.com/image.jpeg",
    "metadata": {},
    "created_at": "2025-07-16T11:35:17.280Z"
}
```

<table><thead><tr><th width="257.7734375">Field</th><th width="164.38671875">Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td><code>string</code></td><td>The Id of the chat</td></tr><tr><td><code>title</code></td><td><code>string</code></td><td>The title of the chat</td></tr><tr><td><code>avatar</code></td><td>string</td><td>The avatar of the chat</td></tr><tr><td><code>participant_user_ids</code></td><td><code>string</code></td><td>User Ids of the participants of the chat</td></tr><tr><td><code>created_at</code></td><td><code>date</code></td><td>date created</td></tr><tr><td><code>metadata</code></td><td><code>json object</code></td><td>an optional key value pair for any additional chat information.</td></tr></tbody></table>

### AI Agent Action

Is triggered when an action configured on an AI agent is executed.

```javascript
{
    "event": "ai_handoff",
    "ai_agent_username": "sample_bot",
    "chat_id": "cmc34d3oh0008cy7urxr0f5zn",
    "fields": [
        { fieldName: 'email_address', fieldValue: 'example@gmail.com'  },
        { fieldName: 'newsletter_title', fieldValue: 'The levelup podcast' }
    ]
}
```

<table><thead><tr><th width="180.92578125">Field</th><th width="102.6796875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>event</code></td><td><code>string</code></td><td>The event that has occurred to trigger the webhook, i.e <code>ai_handoff</code></td></tr><tr><td><code>chatbot_username</code></td><td><code>string</code></td><td>The username of the AI agent</td></tr><tr><td><code>chat_id</code></td><td><code>string</code></td><td>The id of the conversation that the AI agent has stopped participating in.</td></tr><tr><td><code>fields</code></td><td><code>object</code></td><td>The fields that were specified as required for the AI agent action on the minchat dashboard.</td></tr></tbody></table>

### New Daily Active User

Is triggered when there is a new daily active user.

```javascript
{
      "id":"639575b2c280a7001e892906",
      "name":"Samantha Smith",
      "username":"samantha",
      "avatar": "urltoavatar.com/mercyavatar.jpg"
}
```

The payload is a [`User`](https://docs.minchat.io/reference/user) object