Conversations webhooks

Here you will find the list of all the Conversation events you can track, along with their schema and parameters.

Conversation Started

Event is triggered when a conversation is started by a visitor or an agent (automatic targeted messages and pushed messages won’t trigger the event).

Attribute name	Data type	Description
`eventName`	string	"conversationStarted"
`conversationId`	string	ID of the continuous conversation with one visitor.
`message`	Message	Initial message
`agent`	Agent	Agent information
`visitor`	Visitor	Visitor information: - country, language, browser, etc. - contact attributes - info from contact form or JS API - info from channel (i.e. Facebook profile) - terms of service and marketing consents - and more!
`conversationStartPage`	Object	For the chat widget, will contain the `link` and `title` of your website at the time the conversation was started.
`isNoAvailableAgent`	Boolean	Shows if no agent is online at this point

{
    "eventName": "conversationStarted",
    "conversationId": "MxhGJAEugdLtS2BBq",
    
    "conversationStartPage": {
      "link": "https://getwear.com/women/151254/",
      "title": "Washed skinny jeans for women"
    }

    // initial message (see “The Message object” below)
    // https://developers.brevo.com/docs/conversations-webhooks#the-message-object
    "message": {
        "id": "dkmyYPxJyh5rKDhRT",
        // `type` can be `agent` or `visitor`
        "type": "agent",
        "text": "Hi there! Did you receive your tracking number?",
        "html": "Hi there! Did you receive your tracking number?",
        // timestamp in ms
        "createdAt": 1665578322700,
        // agent’s name and ID is passed in case it’s agent’s message
        "agentId": "bnRzp4CioKudG4aHm",
        "agentName": "Julia",
        // only set when the agent has uploaded a profile picture
        "agentUserpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/"
    },

    // agent info is passed in case chat was started by an agent
    "agent": {
        "id": "bnRzp4CioKudG4aHm",
        "name": "Julia",
        "email": "[email protected]",
        // only set when the agent has uploaded a profile picture
        "userpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/"
    },

    // visitor information
    "visitor": {
        // id generated by Brevo or `visitorId` passed to `window.BrevoConversationsSetup`
        // (see “Binding chat to a user account”: https://developers.brevo.com/docs/customize-the-widget#binding-conversations-to-user-accounts)
        "id": "vfg1y4h4ioapl1cx0trw1mujk6den021zs9b2q8",
        "threadId": "aC4krWMZWLYzz9sKZ",
        // link to this conversation in dashboard
        "threadLink": "https://conversations-app.brevo.com/conversations/aC4krWMZWLYzz9sKZ",
        "source": "widget",
        // For Facebook/Instagram/WhatsApp, the ID of the page/account
        "sourceChannelRef": null,
        // For Facebook/Instagram/WhatsApp, the link of the channel on the platform
        "sourceChannelLink": null,
        // For Facebook/Instagram/WhatsApp, the ID of the visitor on the platform
        "sourceConversationRef": null,
        // id of the agent group
        "groupId": "z2o3F8GDkNpKD4BYt",
        // visitor’s userpic color in Conversations
        "color": "#faebd7",
        "ip": "192.168.1.179",
        // visitor’s browser language
        "browserLanguage": "en-US",
        // language displayed to the visitor
        "conversationLanguage": "en",
        "browser": "Chrome 106.0.0",
        "os": "Windows 10",
        // User agent string
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
        "country": "Ireland",
        "city": "Dublin",
        "lastVisit": {
            // timestamp in ms
            "startedAt": 1664550759104,
            // finishedAt can be undefined for an ongoing visit
            "finishedAt": 1664551471534,
            // last visited website
            "hostName": "getwear.com",
            // list of viewed pages (link + title) during current visit
            "viewedPages": [
                {
                    "link": "https://getwear.com/",
                    "title": "Getwear — custom designer jeans"
                },
                {
                    "link": "https://getwear.com/women/151254/",
                    "title": "Washed skinny jeans for women"
                }
            ]
        },
        // name displayed in dashboard (userpic color name for anonymous visitors, e.g. “Dark Orange”)
        "displayedName": "Jane",
        // Attributes from the contact
        "contactAttributes": {
            "SMS": "35315684258"
        },
        // Information from the contact form or passed to the JS API.
        // (see “Passing user details to Conversations”: https://developers.brevo.com/docs/customize-the-widget#passing-user-details-to-conversations)
        "integrationAttributes": {
            "FIRSTNAME": "Jane",
            "EMAIL": "[email protected]",
            "ORDER": "#151254",
            "CART": "Washed skinny jeans for women, $99"
        },
        // Combination of the two above, priority is given to the information filled by visitor
        // and/or agents. This object should be used over the two above in most cases.
        "attributes": {
            "FIRSTNAME": "Jane",
            "EMAIL": "[email protected]",
            "SMS": "35315684258",
            "ORDER": "#151254",
            "CART": "Washed skinny jeans for women, $99"
        },
        // Attributes that can be formatted only
        "formattedAttributes": {
          "SMS": "+353 1 568 4258"
        },
        "notes": "Loves skinny jeans",
        "contactId": 5,
        "marketingConsent": false,
        "termsOfServiceConsent": true
    }
}

Conversation Fragment

Event is triggered after each message with some exceptions. Will not be triggered in these cases:

Message is an automatic targeted message from an agent.
Visitor’s chat is blocked by a mandatory contact form (“Get messages only once the form is filled” option in contact form settings). In this case, the event will be triggered after the contact form is filled by the visitor.
Message is a pushed message and there are no previous conversations with the visitor.
messages property of the event object contains all the messages since previous conversationFragment event.

📘
This ruleset is designed for two-way integrations with help desks and the like.
The event is only triggered when there’s a message that requires agents’ attention or there’s a response from an agent that should be added to the conversation (i.e. new ticket should be created or an existing ticket should be updated).
That’s why automatic targeted messages do not trigger the event, but are added to the webhook for the sake of completeness the next time the event happens.

Attribute name	Data type	Description
`eventName`	string	"conversationFragment"
`conversationId`	string	ID of the continuous conversation with one visitor.
`messages`	Message[]	List of messages since the previous `conversationFragment` event
`agents`	Object[]	List of agents who participated in this fragment
`visitor`	Visitor	Visitor information: - country, language, browser, etc. - contact attributes - info from contact form or JS API - info from channel (i.e. Facebook profile) - terms of service and marketing consents - and more!
`isNoAvailableAgent`	Boolean	Shows if no agent is online at this point

{
    "eventName": "conversationFragment",
    "conversationId": "aC4krWMZWLYzz9sKZ",

    // list of messages since previous `conversationFragment` event
    // (see “The Message object” below)
    // https://developers.brevo.com/docs/conversations-webhooks#the-message-object
    "messages": [
        // pushed message from an agent (see `pushedMessages` in REST API)
        {
            "type": "agent",
            "id": "AXCR3k9bpSY7bpuh7",
            "text": "Your order has shipped! Here’s your tracking number: 9114 5847 4668 7775 9233 54",
          	"html": "Your order has shipped! Here&39;s your tracking number: 9114 5847 4668 7775 9233 54",
            "createdAt": 1664550379561,
            "agentId": "d9nKoegKSjmCtyK78",
            "agentName": "Liz",
            // only set when the agent has uploaded a profile picture
            "agentUserpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/",
            // `true` for pushed messages
            "isPushed": true
        },

        // automatic targeted message from an agent
        {
            "type": "agent",
            "id": "DftGtKqyJpBXtC42J",
            "text": "Hi there! How can we help you?",
            "html": "Hi there! How can we help you?",
            "createdAt": 1664554934355,
            "agentId": "bnRzp4CioKudG4aHm",
            "agentName": "Julia",
            // only set when the agent has uploaded a profile picture
            "agentUserpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/",
            // `true` for automatic messages from “Targeted chats & triggers”
            "isTrigger": true
        },

        // visitor’s message
        {
            "type": "visitor",
            "id": "JuzQe8pJ9cZqymJK9",
            "text": "I’ve changed my email, could you please re-send my order details?",
            "html": "I&39;ve changed my email, could you please re-send my order details?",
            "createdAt": 1664563333617
        }
    ],

    // list of agents who participated in this fragment
    "agents": [
        {
            "id": "d9nKoegKSjmCtyK78",
            "name": "Liz",
            "email": "[email protected]",
            // only set when the agent has uploaded a profile picture
            "userpic": "https://ucarecdn.com/93d1e396-2a78-4ece-82f0-7b8bb9043b78/"
        },

        {
            "id": "bnRzp4CioKudG4aHm",
            "name": "Julia",
            "email": "[email protected]",
            // only set when the agent has uploaded a profile picture
            "userpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/"
        }
    ],

    // visitor information
    "visitor": {
  
        // id generated by Brevo or `visitorId` passed to `window.BrevoConversationsSetup`
        // (see “Binding chat to a user account”: https://developers.brevo.com/docs/customize-the-widget#binding-conversations-to-user-accounts)
        "id": "vfg1y4h4ioapl1cx0trw1mujk6den021zs9b2q8",
        "threadId": "aC4krWMZWLYzz9sKZ",
        // link to this conversation in dashboard
        "threadLink": "https://conversations-app.brevo.com/conversations/aC4krWMZWLYzz9sKZ",
        "source": "widget",
        // For Facebook/Instagram/WhatsApp, the ID of the page/account
        "sourceChannelRef": null,
        // For Facebook/Instagram/WhatsApp, the link of the channel on the platform
        "sourceChannelLink": null,
        // For Facebook/Instagram/WhatsApp, the ID of the visitor on the platform
        "sourceConversationRef": null,
        // id of the agent group
        "groupId": "z2o3F8GDkNpKD4BYt",
        // visitor’s userpic color in Conversations
        "color": "#faebd7",
        "ip": "192.168.1.179",
        // visitor’s browser language
        "browserLanguage": "en-US",
        // language displayed to the visitor
        "conversationLanguage": "en",
        "browser": "Chrome 106.0.0",
        "os": "Windows 10",
        // User agent string
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
        "country": "Ireland",
        "city": "Dublin",
        "lastVisit": {
            // timestamp in ms
            "startedAt": 1664550759104,
            // finishedAt can be undefined for an ongoing visit
            "finishedAt": 1664551471534,
            // last visited website
            "hostName": "getwear.com",
            // list of viewed pages (link + title) during current visit
            "viewedPages": [
                {
                    "link": "https://getwear.com/",
                    "title": "Getwear — custom designer jeans"
                },
                {
                    "link": "https://getwear.com/women/151254/",
                    "title": "Washed skinny jeans for women"
                }
            ]
        },
        // name displayed in dashboard (userpic color name for anonymous visitors, e.g. “Dark Orange”)
        "displayedName": "Jane",
        // Attributes from the contact
        "contactAttributes": {
            "SMS": "35315684258"
        },
        // Information from the contact form or passed to the JS API.
        // (see “Passing user details to Conversations”: https://developers.brevo.com/docs/customize-the-widget#passing-user-details-to-conversations)
        "integrationAttributes": {
            "FIRSTNAME": "Jane",
            "EMAIL": "[email protected]",
            "ORDER": "#151254",
            "CART": "Washed skinny jeans for women, $99"
        },
        // Combination of the two above, priority is given to the information filled by visitor
        // and/or agents. This object should be used over the two above in most cases.
        "attributes": {
            "FIRSTNAME": "Jane",
            "EMAIL": "[email protected]",
            "SMS": "35315684258",
            "ORDER": "#151254",
            "CART": "Washed skinny jeans for women, $99"
        },
        // Attributes that can be formatted only
        "formattedAttributes": {
          "SMS": "+353 1 568 4258"
        },
        "notes": "Loves skinny jeans",
        "contactId": 5,
        "marketingConsent": false,
        "termsOfServiceConsent": true
    }
}

Conversation Transcript

Event is triggered when a conversation is finished. Conversation is considered finished after the visitor goes offline (leaves your website) or all the agents who participated leave the conversation.

Attribute name	Data type	Description
`eventName`	string	"conversationTranscript"
`conversationId`	string	ID of the continuous conversation with one visitor.
`messages`	Message[]	List of messages
`missedMessagesCount`	Number	Number of missed and offline messages
`agents`	Object[]	List of agents who participated in the conversation
`visitor`	Visitor	Visitor information: - country, language, browser, etc. - contact attributes - info from contact form or JS API - info from channel (i.e. Facebook profile) - terms of service and marketing consents - and more!
`conversationStartPage`	Object	For the chat widget, will contain the `link` and `title` of your website at the time the conversation was started.

{
    "eventName": "conversationTranscript",
    "conversationId": "aC4krWMZWLYzz9sKZ",
    
    // For the chat widget, will contain the `link` and `title` of your website at the time the conversation was started
    "conversationStartPage": {
      "link": "https://getwear.com/women/151254/",
      "title": "Washed skinny jeans for women"
    }

    // list of messages (see “The Message object” below)
    // https://developers.brevo.com/docs/conversations-webhooks#the-message-object
    "messages": [
        // pushed message from an agent (see `pushedMessages` in REST API)
        {
            "type": "agent",
            "id": "AXCR3k9bpSY7bpuh7",
            "text": "Your order has shipped! Here’s your tracking number: 9114 5847 4668 7775 9233 54",
            "html": "Your order has shipped! Here&#39;s your tracking number: 9114 5847 4668 7775 9233 54",
            "createdAt": 1664550379561,
            "agentId": "d9nKoegKSjmCtyK78",
            "agentName": "Liz",
            // only set when the agent has uploaded a profile picture
            "agentUserpic": "https://ucarecdn.com/93d1e396-2a78-4ece-82f0-7b8bb9043b78/",
            // `true` for pushed messages
            "isPushed": true
        },

        // automatic targeted message from an agent
        {
            "type": "agent",
            "id": "DftGtKqyJpBXtC42J",
            "text": "Hi there! How can we help you?",
            "html": "Hi there! How can we help you?",
            "createdAt": 1664554934355,
            "agentId": "bnRzp4CioKudG4aHm",
            "agentName": "Julia",
            // only set when the agent has uploaded a profile picture
            "agentUserpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/",
            // `true` for automatic messages from “Targeted chats & triggers”
            "isTrigger": true
        },

        // visitor’s message
        {
            "type": "visitor",
            "id": "JuzQe8pJ9cZqymJK9",
            "text": "I’ve changed my email, could you please re-send my order details?",
            "html": "I&39;ve changed my email, could you please re-send my order details?",
            "createdAt": 1664563333617
        },

        // agent’s message
        {
            "type": "agent",
            "id": "5z5fvBj4auebD63S5",
            "text": "Sure, just a moment :)",
            "html": "Sure, just a moment :)",
            "createdAt": 1664563359830,
            "agentId": "bnRzp4CioKudG4aHm",
            "agentName": "Julia",
            // only set when the agent has uploaded a profile picture
            "agentUserpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/",
        },

        // agent sends a file
        {
            "type": "agent",
            "id": "5MzkBA9ERXJNk4JuH",
            "text": "receipt.png",
            // Sanitized file name
            "html": "receipt.png",
            "file": {
                "name": "receipt.png",
                // size in bytes
                "size": 333455,
                "isAllowedFileType": true,
                // whether the file is an image
                "isImage": true,
                "isSticker": true,
                "link": "https://ucarecdn.com/03cd56cd-1de9-4f65-996d-08afdf27fa1b/",
                // image info is passed in case the file is an image
                "imageInfo": {
                    "width": 1129,
                    "height": 525,
                    "previewUrl": "https://ucarecdn.com/03cd56cd-1de9-4f65-996d-08afdf27fa1b/-/preview/800x800/-/quality/lighter/"
                }
            },
            "createdAt": 1664563366078,
            "agentId": "bnRzp4CioKudG4aHm",
            "agentName": "Julia",
            // only set when the agent has uploaded a profile picture
            "agentUserpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/"
        },

        {
            "type": "visitor",
            "id": "6QZDugATac9FXZSkp",
            "text": "Thanks!",
            "html": "Thanks!",
            "createdAt": 1664563372326,
            // `true` for missed and offline messages
            "isMissed": true
        }
    ],

    // number of missed and offline messages
    "missedMessagesCount": 1,

    // list of agents who participated in the conversation
    "agents": [
        {
            "id": "d9nKoegKSjmCtyK78",
            "name": "Liz",
            "email": "[email protected]",
            // only set when the agent has uploaded a profile picture
            "userpic": "https://ucarecdn.com/93d1e396-2a78-4ece-82f0-7b8bb9043b78/"
        },

        {
            "id": "bnRzp4CioKudG4aHm",
            "name": "Julia",
            "email": "[email protected]",
            // only set when the agent has uploaded a profile picture
            "userpic": "https://ucarecdn.com/06e119c4-debd-420f-bb8c-7a2f261ca0e5/"
        }
    ],

    // visitor information
    "visitor": {
        // id generated by Brevo or `visitorId` passed to `window.BrevoConversationsSetup`
        // (see “Binding chat to a user account”: https://developers.brevo.com/docs/customize-the-widget#binding-conversations-to-user-accounts)
        "id": "vfg1y4h4ioapl1cx0trw1mujk6den021zs9b2q8",
        "threadId": "aC4krWMZWLYzz9sKZ",
        // link to this conversation in dashboard
        "threadLink": "https://conversations-app.brevo.com/conversations/aC4krWMZWLYzz9sKZ",
        "source": "widget",
        // For Facebook/Instagram/WhatsApp, the ID of the page/account
        "sourceChannelRef": null,
        // For Facebook/Instagram/WhatsApp, the link of the channel on the platform
        "sourceChannelLink": null,
        // For Facebook/Instagram/WhatsApp, the ID of the visitor on the platform
        "sourceConversationRef": null,
        // id of the agent group
        "groupId": "z2o3F8GDkNpKD4BYt",
        // visitor’s userpic color in Conversations
        "color": "#faebd7",
        "ip": "192.168.1.179",
        // visitor’s browser language
        "browserLanguage": "en-US",
        // language displayed to the visitor
        "conversationLanguage": "en",
        "browser": "Chrome 106.0.0",
        "os": "Windows 10",
        // User agent string
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
        "country": "Ireland",
        "city": "Dublin",
        "lastVisit": {
            // timestamp in ms
            "startedAt": 1664550759104,
            // finishedAt can be undefined for an ongoing visit
            "finishedAt": 1664551471534,
            // last visited website
            "hostName": "getwear.com",
            // list of viewed pages (link + title) during current visit
            "viewedPages": [
                {
                    "link": "https://getwear.com/",
                    "title": "Getwear — custom designer jeans"
                },
                {
                    "link": "https://getwear.com/women/151254/",
                    "title": "Washed skinny jeans for women"
                }
            ]
        },
        // name displayed in dashboard (userpic color name for anonymous visitors, e.g. “Dark Orange”)
        "displayedName": "Jane",
        // Attributes from the contact
        "contactAttributes": {
            "SMS": "35315684258"
        },
        // Information from the contact form or passed to the JS API.
        // (see “Passing user details to Conversations”: https://developers.brevo.com/docs/customize-the-widget#passing-user-details-to-conversations)
        "integrationAttributes": {
            "FIRSTNAME": "Jane",
            "EMAIL": "[email protected]",
            "ORDER": "#151254",
            "CART": "Washed skinny jeans for women, $99"
        },
        // Combination of the two above, priority is given to the information filled by visitor
        // and/or agents. This object should be used over the two above in most cases.
        "attributes": {
            "FIRSTNAME": "Jane",
            "EMAIL": "[email protected]",
            "SMS": "35315684258",
            "ORDER": "#151254",
            "CART": "Washed skinny jeans for women, $99"
        },
        // Attributes that can be formatted only
        "formattedAttributes": {
          "SMS": "+353 1 568 4258"
        },
        "notes": "Loves skinny jeans",
        "contactId": 5,
        "marketingConsent": false,
        "termsOfServiceConsent": true
    }
}

The Visitor object

Attribute name	Data type	Description
`source`	string	Source of the visitor, e.g. `widget`, `facebook`, `whatsapp`, etc.
`displayedName`	string	Name displayed in dashboard (userpic color name for anonymous visitors, e.g. “Dark Orange”)
`contactId`	Number	If the visitor is in your Contacts, its ID will be available here.
`contactAttributes`	Object	Info from your Brevo contact.
`integrationAttributes`	Object	Info from the integration. Examples: - For the chat widget, it will be the info from the contact form or the JS API. - Info from channel (i.e. Facebook profile)
`attributes`	Object	Combination of the two above. Priority is given to the contact attributes. This object should be used over the two above in most cases
`formattedAttributes`	Object	Display name for attributes that can be formatted (`SMS`, `WHATSAPP`)
`termsOfServiceConsent`	Boolean	Useful if you have enabled "Request consent to your terms" in the Contact form, and the conversation was started by the chat widget (not applicable for other channels like Instagram or Facebook)
`marketingConsent`	Boolean	Useful if you have enabled "Request consent to your marketing communications" in the Contact form, and the conversation was started by the chat widget (not applicable for other channels like Instagram or Facebook)
`browser` / `country` / `lastVisit` / etc.		More fields are available in this object, please check the sample payloads to find out.

The Agent object

Attribute name	Data type	Description
`id`	string	ID of the agent, as found in the agent's page.
`name`	string	Name of the agent
`email`	string	Email address of the agent
`userpic`	string	URL of the agent's profile photo, if they have uploaded one

The Message object

Attribute name	Data type	Description
`id`	String	Message ID.
`type`	String	`visitor` or `agent` (depending on who sent the message).
`text`	String	Message text or name of the attached file.
`html`	String	Safe HTML with our chat “markdown” applied.
`createdAt`	Number	Timestamp in milliseconds.
`agentId`	String	Agent’s ID in the messages sent by an agent.
`agentName`	String	Agent’s name as displayed to the visitor. Only in the messages sent by an agent.
`agentUserpic`	String	URL of the agent's profile photo, if they have uploaded one
`messageType`	String	Contains “email_bounce” when the received answer is a bounce notification received from Gmail
`isTrigger`	Boolean	`true` for automatic messages from “Targeted chats & triggers”
`isPushed`	Boolean	For automated messages.
`isMissed`	Boolean	When the chat is finished, visitor’s messages missed by the agents are marked with `"isMissed": true`.
`isMissedByVisitor`	Boolean	When the chat is finished, agent’s messages missed by the visitor are marked with `"isMissedByVisitor": true`.
`receivedFrom`	String	In two-way integrations, messages sent via REST API can be marked with receivedFrom property and then filtered out when received in a webhook to avoid infinite loop.
`file`	Attachment object	Attachment messages have this property containing file information.
`attachments`	Attachment[] object	This can exists in email replies to chat conversations. Unlike `file`, `attachments` exist alongside the regular message

The Attachment object

Attribute name	Data type	Description
`name`	String	Name of the file.
`size`	Number	Size in bytes.
`isImage`	Boolean	Whether the file is an image.
`isSticker`	Boolean	For stickers (Facebook/Instagram/WhatsApp)
`link`	String	URL of the file.
`isAllowedFileType`	Boolean	Whether the file type is allowed in this setting.
`imageInfo`	Object	In case the file is an image, will contain `width`, `height` and `previewLink`.

Conversation Started

Conversation Fragment

📘This ruleset is designed for two-way integrations with help desks and the like.

Conversation Transcript

The Visitor object

The Agent object

The Message object

The Attachment object

📘
This ruleset is designed for two-way integrations with help desks and the like.