Conversations webhooks

Create and manage Conversations webhooks in Conversations > Settings > Integrations > 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 nameData typeDescription
eventNamestring"conversationStarted"
conversationIdstringID of the continuous conversation with one visitor.
messageMessageInitial message
agentAgentAgent information
visitorVisitorVisitor 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!
conversationStartPageObjectFor the chat widget, will contain the link and title of your website at the time the conversation was started.
{
    "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 nameData typeDescription
eventNamestring"conversationFragment"
conversationIdstringID of the continuous conversation with one visitor.
messagesMessage[]List of messages since the previous conversationFragment event
agentsObject[]List of agents who participated in this fragment
visitorVisitorVisitor 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!
{
    "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 nameData typeDescription
eventNamestring"conversationTranscript"
conversationIdstringID of the continuous conversation with one visitor.
messagesMessage[]List of messages
missedMessagesCountNumberNumber of missed and offline messages
agentsObject[]List of agents who participated in the conversation
visitorVisitorVisitor 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!
conversationStartPageObjectFor 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'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 nameData typeDescription
sourcestringSource of the visitor, e.g. widget, facebook, whatsapp, etc.
displayedNamestringName displayed in dashboard (userpic color name for anonymous visitors, e.g. “Dark Orange”)
contactIdNumberIf the visitor is in your Contacts, its ID will be available here.
contactAttributesObjectInfo from your Brevo contact.
integrationAttributesObjectInfo 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)
attributesObjectCombination of the two above.
Priority is given to the contact attributes.
This object should be used over the two above in most cases
formattedAttributesObjectDisplay name for attributes that can be formatted (SMS, WHATSAPP)
termsOfServiceConsentBooleanUseful 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)
marketingConsentBooleanUseful 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 nameData typeDescription
idstringID of the agent, as found in the agent's page.
namestringName of the agent
emailstringEmail address of the agent
userpicstringURL of the agent's profile photo, if they have uploaded one

The Message object

Attribute nameData typeDescription
idStringMessage ID.
typeStringvisitor or agent (depending on who sent the message).
textStringMessage text or name of the attached file.
htmlStringSafe HTML with our chat “markdown” applied.
createdAtNumberTimestamp in milliseconds.
agentIdStringAgent’s ID in the messages sent by an agent.
agentNameStringAgent’s name as displayed to the visitor. Only in the messages sent by an agent.
agentUserpicStringURL of the agent's profile photo, if they have uploaded one
isTriggerBooleantrue for automatic messages from “Targeted chats & triggers
isPushedBooleanFor automated messages.
isMissedBooleanWhen the chat is finished, visitor’s messages missed by the agents are marked with "isMissed": true.
isMissedByVisitorBooleanWhen the chat is finished, agent’s messages missed by the visitor are marked with "isMissedByVisitor": true.
receivedFromStringIn 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.
fileAttachment objectAttachment messages have this property containing file information.
attachmentsAttachment[] objectThis can exists in email replies to chat conversations. Unlike file, attachments exist alongside the regular message

The Attachment object

Attribute nameData typeDescription
nameStringName of the file.
sizeNumberSize in bytes.
isImageBooleanWhether the file is an image.
isStickerBooleanFor stickers (Facebook/Instagram/WhatsApp)
linkStringURL of the file.
isAllowedFileTypeBooleanWhether the file type is allowed in this setting.
imageInfoObjectIn case the file is an image, will contain width, height and previewLink.