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, 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.

payload

{
   "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": {}
}

Field	Type	Description
sent_by	User	The user that sent the message
sent_to	User[]	An array of users that have received the message
text	string	The content of the message
file	File	A file attachment associated with this message
chat_id	string	The id of the conversation this message was sent to
metadata	json object	an optional key value pair for any additional message information.
chat_metadata	json object	an optional key value pair for any additional chat information.

New Conversation

Is triggered when a new conversation is created

{
    "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"
}

Field	Type	Description
id	string	The Id of the chat
title	string	The title of the chat
avatar	string	The avatar of the chat
participant_user_ids	string	User Ids of the participants of the chat
created_at	date	date created
metadata	json object	an optional key value pair for any additional chat information.

AI Agent Action

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

{
    "event": "ai_handoff",
    "ai_agent_username": "sample_bot",
    "chat_id": "cmc34d3oh0008cy7urxr0f5zn",
    "fields": [
        { fieldName: 'email_address', fieldValue: '[email protected]'  },
        { fieldName: 'newsletter_title', fieldValue: 'The levelup podcast' }
    ]
}

Field	Type	Description
event	string	The event that has occurred to trigger the webhook, i.e ai_handoff
chatbot_username	string	The username of the AI agent
chat_id	string	The id of the conversation that the AI agent has stopped participating in.
fields	object	The fields that were specified as required for the AI agent action on the minchat dashboard.

New Daily Active User

Is triggered when there is a new daily active user.

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

The payload is a User object