JavaScript API reference

Settings

Settings are defined via the window.BrevoConversationsSetup object before the widget code, for example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    chatHeight: 350,
4
    colors: {
5
        buttonText: '#f600a5',
6
        buttonBg: '#fff'
7
    },
8
    startHidden: true
9
};
10
</script>
11
12
<!-- Brevo Conversations widget code -->

buttonStyle

String

Chat button style. Overrides the style set in widget settings. Possible values:

• 'tab'
• 'round'

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    buttonStyle: 'round'
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

buttonPosition

String

Chat button position. Overrides the position set in widget settings. Possible values:

• 'bl' – at the bottom of the screen, on the left,
• 'bc' – at the bottom of the screen, in the middle,
• 'br' – at the bottom of the screen, on the right,
• 'lt' – on the left side of the screen, at the top,
• 'lm' – on the left side of the screen, in the middle,
• 'lb' – on the left side of the screen, at the bottom,
• 'rt' – on the right side of the screen, at the top,
• 'rm' – on the right side of the screen, in the middle,
• 'rb' – on the right side of the screen, at the bottom.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    buttonPosition: 'bl'
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

You can also change the position using setButtonPosition method.

buttonSize

Number

Round chat button size in px, default is 60. Does not affect the “tab” button. You can also change the size of the round chat button using the setButtonSize method.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    buttonSize: 75
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

customWidgetButton

String

Set any valid CSS selector as the customWidgetButton to assign the chat button behavior to an element of your choice. This also hides the default chat button. Set this before the widget code.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    customWidgetButton: '.custom-chat-button'
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

chatWidth

Number

Chat widget width in px, default is 380. The minimum value is 280. You can also change the width using the setChatWidth method.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    chatWidth: 280
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

chatHeight

Number

Chat widget height in px, default is 600. The minimum value is 300. You can also change the height using the setChatHeight method.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    chatHeight: 400
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

zIndex

Number

Chat widget’s z-index value, default is 9999. You can also change the z-index using the setZIndex method.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    zIndex: 10
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

colors

Object

Defines the color scheme of the widget. Colors are set using strings in #fff or #ffffff format:

1
<script>
2
window.BrevoConversationsSetup = {
3
    colors: {
4
        buttonText: '#f5f5f5', /* chat button text/icon color */
5
        buttonBg: '#5ece1a', /* chat button background color */
6
        visitorBubbleBg: '#e7ffd1', /* visitor’s message bubble color */
7
        agentBubbleBg: '#deffff' /* agent’s message bubble color */
8
    }
9
};
10
</script>
11
12
<!-- Brevo Conversations widget code -->

Custom message bubble colors work in browsers that support CSS variables. Browsers without CSS variable support display default colors.

You can also change the color scheme of the widget using the setColors method.

startHidden

Boolean

If set to true, the widget starts hidden. You can also show and hide the widget using the show and hide methods.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    startHidden: true
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

mobileOnly

Boolean

If set to true, the widget appears only on mobile devices.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    mobileOnly: true
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

disabledOnMobile

Boolean

If set to true, the widget doesn’t appear on mobile devices.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    disabledOnMobile: true
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

language

String

Widget language. Overrides the language set in widget settings. Possible values: 'en', 'de', 'fr', 'es', 'nl', 'pt', 'it', and 'ru'.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    language: 'fr'
4
};
5
</script>
6
7
<!-- Brevo Conversations widget code -->

locale

Object

Lets you change any number of the default locale strings. Override individual strings, or all of them to translate the widget into an unsupported language.

See Translating the widget for details.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    locale: {
4
        chat: {
5
            input: {
6
                placeholder: 'Scrivi un messaggio...'
7
            }
8
        },
9
        contactAttributes: {
10
            firstName: 'Nome',
11
            lastName: 'Cognome',
12
        },
13
        messageTypes: {
14
            joinedFirst: 'entrato in chat',
15
            joined: '{{#username}} entrato in chat',
16
            agentsOffline: 'Operatore Offline'
17
        }
18
    }
19
};
20
</script>
21
22
<!-- Brevo Conversations widget code -->

You can also modify the locale dynamically using the setLocale method.

mode

String

Conversations display mode:

• 'widget' — default widget,
• 'frame' — Conversations is embedded into the block specified in injectTo.

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    mode: 'frame',
4
    injectTo: 'conversations-wrapper'
5
};
6
</script>
7
8
<!-- Brevo Conversations widget code -->

injectTo

String | Array | Object

Specifies the element Brevo Conversations is embedded into when launched in frame mode (see mode). Possible values: the element’s id, a direct link to the HTML Node, or an array-like HTML Node collection, including NodeLists and jQuery collections (the first element of the collection is used).

Example:

1
<script>
2
window.BrevoConversationsSetup = {
3
    mode: 'frame',
4
    injectTo: 'conversations-wrapper'
5
};
6
</script>
7
8
<!-- Brevo Conversations widget code -->

If you use an HTML node or a collection, ensure the required element is available when the BrevoConversationsSetup object is defined (place the definition before the closing </body> tag or run it after the DOMContentLoaded event). If you specify the element’s id instead, Conversations searches for the element automatically after the DOMContentLoaded event.

visitorId

String

Unique secret string (not available to other users). Binds the chat to a signed-in user.

visitorId must be unique and secret (not available to other users), since knowing it could grant access to the conversation. Use a randomly generated string. Do not use publicly known data such as a user’s ID, name, or email.

See Binding conversations to user accounts.

Example:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        visitorId: 'kZMvWhf8npAu3H6qd57w2Hv6nh6rnxvg'
4
    };
5
</script>
6
7
<!-- Brevo Conversations widget code -->

groupId

String

Agent group ID. Chats started on a page with this group ID set are assigned to this group. You can find the group’s ID on its page in Conversations’ “Groups” settings.

Example:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        groupId: 'z2o3F8GDkNpKD4BYt'
4
    };
5
</script>
6
7
<!-- Brevo Conversations widget code -->

You can also change the agent group ID using the setGroupId method.

gaTrackingId

String

Sets a specific Google Analytics tracking ID to send Brevo Conversations events to.

You only need to set this if you have several GA trackers on the same page. Otherwise, Brevo Conversations sends events to Google Analytics automatically using the first GA tracker it finds on the page.

Example:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        gaTrackingId: 'UA-12345678-1'
4
    };
5
</script>
6
7
<!-- Brevo Conversations widget code -->

disableGaTracking

Boolean

Set this option to true to prevent Brevo Conversations from sending events to Google Analytics.

Example:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        disableGaTracking: true
4
    };
5
</script>
6
7
<!-- Brevo Conversations widget code -->

onNewMessage

Function

A callback function called every time a new message arrives.

The function receives the message details as an argument:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        onNewMessage: function(message) {
4
            console.log('New message:', message);
5
        }
6
    };
7
</script>
8
9
<!-- Brevo Conversations widget code -->

The message object includes the following keys:

1
{
2
    createdAt: 1482512803740
3
    id: "eYBEm3gq3zc5ayE2g"​
4
    text: "Hello! How can I help you?"
5
    type: "agent"
6
}

id — message ID. Used for further operations on the message.

createdAt — timestamp in milliseconds.

type — "agent" for agents’ messages, "visitor" for visitors’ messages, and "bot" for automated scripts.

onAnalyticEvent

Function

A callback function called every time one of the analytic events listed below occurs.
Events not initiated by visitors have a non-interaction flag. Google Analytics excludes these events when calculating the bounce rate.

Chat initiated by visitor
     A visitor initiated the chat by sending a message.

Chat initiated by agent (non-interaction event)
     An agent initiated the chat by writing a message in the existing conversation after a period of inactivity.

Chat accepted by agent (non-interaction event)
     An agent replied to a new chat from a visitor.

Chat rated
     A visitor rated the conversation.

Targeted chat shown (non-interaction event)
     A chat window was shown to a visitor (according to the “Targeted chats & triggers” settings).

Targeted chat accepted by visitor
     A visitor replied to the chat initiated by a trigger.

Targeted chat rejected by visitor
     A visitor closed the chat initiated by a trigger.

Pre-chat form shown (non-interaction event)
     Contact form was shown to a visitor.

Pre-chat form submitted
     Contact form was submitted by a visitor.

Bot scenario shown (non-interaction event)
     Chatbot scenario was shown to a visitor.

Bot scenario started by visitor
     A visitor started a chatbot scenario.

Bot reply option clicked
     A visitor clicked on a reply option in a chatbot scenario.

The function receives event name as an argument:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        onAnalyticEvent: function(eventName) {
4
            console.log('An event just happend:', eventName);
5
        }
6
    };
7
</script>
8
9
<!-- Brevo Conversations widget code -->

Brevo Conversations sends these events to Google Analytics automatically. Use this setting to pass Brevo Conversations events to other analytic systems.

deferredLoading

Boolean

If set to true, the widget starts loading only after all other page resources have finished loading.

This may improve your score in tools like PageSpeed Insights, but the chat button takes longer to appear.

Example:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        deferredLoading: true
4
    };
5
</script>
6
7
<!-- Brevo Conversations widget code -->

disableChatOpenHash

Boolean

When a visitor opens a chat window on a mobile device, #brevoConversationsExpanded is added to the page address. This lets the visitor close the chat window using the “back” button, but in rare cases it may conflict with some single-page applications.

Set this option to true to disable the behavior:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        disableChatOpenHash: true
4
    };
5
</script>
6
7
<!-- Brevo Conversations widget code -->

Methods

Methods dynamically change the behavior of the chat widget. Call them anywhere after the widget code, for example:

1
<!-- Brevo Conversations widget code -->
2
3
<script>
4
    BrevoConversations('expandWidget');
5
</script>

Method calls made before Brevo Conversations finishes loading are queued and executed once Brevo Conversations is ready.

sendAutoMessage

BrevoConversations('sendAutoMessage', text)

text – string containing the text of your message.

Sends an automatic message on behalf of a random agent. Works the same way as automatic targeted messages, but lets you define custom logic and control what is sent and when.

Example:

1
BrevoConversations('sendAutoMessage', 'Hi there 👋 Chat with us if you need a hand');

sendVisitorMessage

BrevoConversations('sendAutoMessage', text, {groupId})

text – String containing the text of the message.

groupId – (optional) Sets agent group ID. You can find the group’s ID on its page in Conversations “Groups” settings. Use null to reset the group ID. If not defined and the “Ask visitors to select a group” setting is enabled, the visitor may be asked to select the group before the message is sent.

Sends a message on behalf of a visitor.

Example:

1
BrevoConversations('sendVisitorMessage', 'I need help with my order');

startBotScenario

BrevoConversations('startBotScenario', scenarioId)

scenarioId – scenario ID, found on the scenario’s page.

Starts a chatbot scenario.

Example:

1
BrevoConversations('startBotScenario', 'V3RYmUCHcUt3D0g3');

setButtonPosition

BrevoConversations('setButtonPosition', positionCode)

Sets the chat button position. Overrides the position set in widget settings.

positionCode – chat button position code. Possible values:

• 'bl' – at the bottom of the screen, on the left,
• 'bc' – at the bottom of the screen, in the middle,
• 'br' – at the bottom of the screen, on the right,
• 'lt' – on the left side of the screen, at the top,
• 'lm' – on the left side of the screen, in the middle,
• 'lb' – on the left side of the screen, at the bottom,
• 'rt' – on the right side of the screen, at the top,
• 'rm' – on the right side of the screen, in the middle,
• 'rb' – on the right side of the screen, at the bottom.

You can also set the position using the buttonPosition setting.

resetButtonPosition

BrevoConversations('resetButtonPosition')

• Resets the chat button position to the one specified in Brevo Conversations Settings.

setButtonSize

BrevoConversations('setButtonSize', size)

size – positive integer, default is 60.

Sets the size of the round chat button in px. Does not affect the “tab” button. You can also set the round chat button size using the buttonSize setting.

setChatWidth

BrevoConversations('setChatWidth', width)

width – positive integer, default is 380. The minimum value is 280.

Sets the width of the chat widget in px. You can also set the widget width using the chatWidth setting.

setChatHeight

BrevoConversations('setChatHeight', height)

height – positive integer, default is 600. The minimum value is 300.

Sets the height of the chat widget in px. You can also set the widget height using the chatHeight setting.

setZIndex

BrevoConversations('setZIndex', zIndex)

zIndex – integer, default is 9999.

Sets the chat widget’s z-index value. You can also set z-index using the zIndex setting.

setColors

BrevoConversations('setColors', colors)

Sets the color scheme of the widget.

colors — object containing the colors of various widget elements. Colors are set as strings in #fff or #ffffff format:

1
BrevoConversations('setColors', {
2
    buttonText: '#f5f5f5', /* chat button text/icon color */
3
    buttonBg: '#5ece1a', /* chat button background color */
4
    visitorBubbleBg: '#e7ffd1', /* visitor’s message bubble color */
5
    agentBubbleBg: '#deffff' /* agent’s message bubble color */
6
});

Custom message bubble colors work in browsers that support CSS variables. Browsers that don’t support CSS variables will show default colors.

You can also set the color scheme of the widget using colors setting.

resetColors

BrevoConversations('resetColors')

Resets the colors set with the colors setting or setColors method.

openChat

BrevoConversations('openChat'[, focus])

Expands the chat window. Works on both desktop and mobile devices.

The expanded chat window occupies the entire screen on mobile devices. If that isn’t what you want, use the expandWidget method instead.

focus – optional flag. If set to true, the chat input field is focused after the widget expands. Ignored on mobile devices.

expandWidget

BrevoConversations('expandWidget'[, focus])

Expands the chat window. Has no effect on mobile devices.

To expand the chat window on both desktop and mobile devices, use the openChat method instead.

focus – optional flag. If set to true, the chat input field is focused after the widget expands.

minimizeWidget

BrevoConversations('minimizeWidget')

Minimizes the chat window.

hide

BrevoConversations('hide')

Hides the widget. You can also hide the widget using the startHidden setting.

show

BrevoConversations('show')

Shows the widget hidden by the startHidden setting or hide method.

pageView

BrevoConversations('pageView')

Sends a page view to Conversations. If your website or web app loads pages dynamically and updates the document’s URL without a full page load, use this method to track these views in the Conversations right pane.

updateIntegrationData

BrevoConversations('updateIntegrationData', data)

data — object containing any number of properties. Each property’s value must be a String, Number, Boolean, or null.

Updates the visitor’s info in the Conversations right pane. Use null to remove properties:

1
BrevoConversations('updateIntegrationData', {
2
    email: 'cowardly_lion@yahoo.com', /* e-mail changed */
3
    firstName: 'John', /* first name changed */
4
    lastName: 'Doe', /* last name changed */
5
    phone: null, /* phone number removed */
6
    notes: 'Looking for courage...', /* notes property created */
7
8
    /* any number of custom properties */
9
    'trip wish list': 'Going to Oz with friends'
10
});

If custom properties set in updateIntegrationData match existing contact attributes, they sync with your Contacts database. Otherwise, they’re available in Conversations only.

setLocale

BrevoConversations('setLocale', localeModifier)

localeModifier – object containing a modified locale structure.

Lets you change any number of the default locale strings. Override individual strings, or all of them to translate the widget into an unsupported language.

See Translating the widget for details.

Example:

1
BrevoConversations('setLocale', {
2
    chat: {
3
        input: {
4
            placeholder: 'Scrivi un messaggio...'
5
        }
6
    },
7
    contactAttributes: {
8
        firstName: 'Nome',
9
        lastName: 'Cognome',
10
    },
11
    messageTypes: {
12
        joinedFirst: 'entrato in chat',
13
        joined: '{{#username}} entrato in chat',
14
        agentsOffline: 'Operatore Offline'
15
    }
16
});

You can also modify the locale using the locale setting.

setGroupId

BrevoConversations('setGroupId', groupId)

Sets the agent group ID. Chats started with this group ID set are assigned to this group.

You can find the group’s ID on its page in Conversations’ “Groups” settings.

Use null to reset the group ID:

1
BrevoConversations('setGroupId', null);

You can also set the agent group ID using the groupId setting.

restart

BrevoConversations('restart')

Restarts Brevo Conversations.

Use it to update Brevo Conversations settings that can’t be updated through API methods, for example:

1
// Update the settings
2
window.BrevoConversationsSetup = {
3
    language: 'fr'
4
};
5
6
// Restart Brevo Conversations
7
BrevoConversations('restart');

kill

BrevoConversations('kill')

Removes Brevo Conversations completely from the page. Call BrevoConversations('restart') to reinitialize Brevo Conversations.