# 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="/pages/aPDOW0ZeC8SCmThYhzfg"><code>User</code></a></td><td>The user that sent the message</td></tr><tr><td><code>sent_to</code></td><td><a href="/pages/aPDOW0ZeC8SCmThYhzfg"><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="/pages/oo2UbYlOXoRM0U3juf9r"><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`](/reference/user.md) object


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.minchat.io/webhooks/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.