Javascript API reference

Settings

Settings are defined via window.BrevoConversationsSetup object before the widget code, e.g.

<script>
window.BrevoConversationsSetup = {
    chatHeight: 350,
    colors: {
        buttonText: '#f600a5',
        buttonBg: '#fff'
    },
    startHidden: true
};
</script>

<!-- Brevo Conversations widget code -->

`buttonStyle`

String

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

'tab'
'round'

Example:

<script>
window.BrevoConversationsSetup = {
    buttonStyle: 'round'
};
</script>

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

📘
On mobile devices, the “tab” button will always be positioned at the bottom on the screen. The “round” button will have the same position on both desktop and mobile devices.

Example:

<script>
window.BrevoConversationsSetup = {
    buttonPosition: 'bl'
};
</script>

<!-- 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 setButtonSize method.

Example:

<script>
window.BrevoConversationsSetup = {
    buttonSize: 75
};
</script>

<!-- Brevo Conversations widget code -->

`customWidgetButton`

String

Set any valid CSS selector as the customWidgetButton to assign the chat button behavior to the element of your choice (this will also hide the default chat button). To be set before the widget code.

Example:

<script>
window.BrevoConversationsSetup = {
    customWidgetButton: '.custom-chat-button'
};
</script>

<!-- 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 setChatWidth method.

Example:

<script>
window.BrevoConversationsSetup = {
    chatWidth: 280
};
</script>

<!-- 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 setChatHeight method.

Example:

<script>
window.BrevoConversationsSetup = {
    chatHeight: 400
};
</script>

<!-- Brevo Conversations widget code -->

`zIndex`

Number

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

Example:

<script>
window.BrevoConversationsSetup = {
    zIndex: 10
};
</script>

<!-- Brevo Conversations widget code -->

`colors`

Object

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

<script>
window.BrevoConversationsSetup = {
    colors: {
        buttonText: '#f5f5f5', /* chat button text/icon color */
        buttonBg: '#5ece1a', /* chat button background color */
        visitorBubbleBg: '#e7ffd1', /* visitor’s message bubble color */
        agentBubbleBg: '#deffff' /* agent’s message bubble color */
    }
};
</script>

<!-- Brevo Conversations widget code -->

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 change the color scheme of the widget using setColors method.

`startHidden`

Boolean

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

Example:

<script>
window.BrevoConversationsSetup = {
    startHidden: true
};
</script>

<!-- Brevo Conversations widget code -->

`mobileOnly`

Boolean

If set to true the widget will show up only on mobile devices.

Example:

<script>
window.BrevoConversationsSetup = {
    mobileOnly: true
};
</script>

<!-- Brevo Conversations widget code -->

`disabledOnMobile`

Boolean

If set to true the widget won’t show up on mobile devices.

Example:

<script>
window.BrevoConversationsSetup = {
    disabledOnMobile: true
};
</script>

<!-- 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:

<script>
window.BrevoConversationsSetup = {
    language: 'fr'
};
</script>

<!-- Brevo Conversations widget code -->

`locale`

Object

Allows to change any number of the default locale strings. Change the ones you don’t like or all of them to translate the widget to an unsupported language.

See Translating the widget for details.

Example:

<script>
window.BrevoConversationsSetup = {
    locale: {
        chat: {
            input: {
                placeholder: 'Scrivi un messaggio...'
            }
        },
        contactAttributes: {
            firstName: 'Nome',
            lastName: 'Cognome',
        },
        messageTypes: {
            joinedFirst: 'entrato in chat',
            joined: '{{#username}} entrato in chat',
            agentsOffline: 'Operatore Offline'
        }
    }
};
</script>

<!-- Brevo Conversations widget code -->

You can also modify locale dynamically using setLocale method.

`mode`

String

Conversations display mode:

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

Example:

<script>
window.BrevoConversationsSetup = {
    mode: 'frame',
    injectTo: 'conversations-wrapper'
};
</script>

<!-- Brevo Conversations widget code -->

`injectTo`

String | Array | Object

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

Example:

<script>
window.BrevoConversationsSetup = {
    mode: 'frame',
    injectTo: 'conversations-wrapper'
};
</script>

<!-- Brevo Conversations widget code -->

If you are using an HTML node or a collection, make sure it’s possible to receive required element when BrevoConversationsSetup object is defined (e.g. put the definition before closing </body> tag or run it after DOMContentLoaded event). If you specify element’s id instead, Conversations will search for the element after DOMContentLoaded event automatically.

`visitorId`

String

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

visitorId must be unique and secret (i.e. not available for other users) as someone might get the access to the conversation knowing it. It’s best to use randomly generated string. Do not use publicly known data such as user’s ID, name, email, etc.

See “Binding conversations to user accounts”.

Example:

<script>
    window.BrevoConversationsSetup = {
        visitorId: 'kZMvWhf8npAu3H6qd57w2Hv6nh6rnxvg'
    };
</script>

<!-- Brevo Conversations widget code -->

`groupId`

String

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

Example:

<script>
    window.BrevoConversationsSetup = {
        groupId: 'z2o3F8GDkNpKD4BYt'
    };
</script>

<!-- Brevo Conversations widget code -->

You can also change agent group ID using setGroupId method.

`gaTrackingId`

String

This setting allows you to set a specific Google Analytics tracking ID to send Brevo Conversations events to.

There’s no need to set this unless you have several GA trackers in use on the same page. Brevo Conversations sends events to Google Analytics automatically using the first GA tracker it can find on the page.

Example:

<script>
    window.BrevoConversationsSetup = {
        gaTrackingId: 'UA-12345678-1'
    };
</script>

<!-- Brevo Conversations widget code -->

`disableGaTracking`

Boolean

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

Example:

<script>
    window.BrevoConversationsSetup = {
        disableGaTracking: true
    };
</script>

<!-- Brevo Conversations widget code -->

`onNewMessage`

Function

A callback function that is called every time when a new message is there.

The function receives the message details as an argument:

<script>
    window.BrevoConversationsSetup = {
        onNewMessage: function(message) {
            console.log('New message:', message);
        }
    };
</script>

<!-- Brevo Conversations widget code -->

The message object includes the following keys:

{
    createdAt: 1482512803740
    id: "eYBEm3gq3zc5ayE2g"
    text: "Hello! How can I help you?"
    type: "agent"
}

id — message ID. It can be used for further manipulations with 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 that is called every time one of the analytic events listed below happens.
Events not initiated by visitors have a non-interaction flag. Google Analytics doesn't include these events when calculating the bounce rate in statistics.

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:

<script>
    window.BrevoConversationsSetup = {
        onAnalyticEvent: function(eventName) {
            console.log('An event just happend:', eventName);
        }
    };
</script>

<!-- 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 completed loading.

This might improve your score in tools like PageSpeed Insights, but the time it takes for the chat button to appear will increase.

Example:

<script>
    window.BrevoConversationsSetup = {
        deferredLoading: true
    };
</script>

<!-- Brevo Conversations widget code -->

`disableChatOpenHash`

Boolean

When a visitor opens a chat window on mobile devices, #brevoConversationsExpanded gets added to the page address. It allows the visitor to 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 this behavior:

<script>
    window.BrevoConversationsSetup = {
        disableChatOpenHash: true
    };
</script>

<!-- Brevo Conversations widget code -->

Methods

Methods are used to dynamically change the behavior of the chat widget. Methods can be called anywhere after the widget code, for example:

<!-- Brevo Conversations widget code -->

<script>
    BrevoConversations('expandWidget');
</script>

All method calls made before Brevo Conversations finished loading are put into a queue and executed when 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 in the same way as automatic targeted messages, but you can create your own custom logic and have more control over what and when is sent.

Example:

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

`startBotScenario`

BrevoConversations('startBotScenario', scenarioId)

scenarioId – scenario ID. It can be found on scenario’s page.

Start a chatbot scenario.

Example:

BrevoConversations('startBotScenario', 'V3RYmUCHcUt3D0g3');

`setButtonPosition`

BrevoConversations('setButtonPosition', positionCode)

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

📘
On mobile devices, the “tab” button will always be positioned at the bottom on the screen. The “round” button will have the same position on both desktop and mobile devices.

You can also set the position using buttonPosition setting.

`resetButtonPosition`

BrevoConversations('resetButtonPosition')

Resets 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 “tab” button. You can also set the round chat button size using 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 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 chatHeight setting.

`setZIndex`

BrevoConversations('setZIndex', zIndex)

zIndex – integer, default is 9999.

Sets chat widget’s z-index value. You can also set z-index using 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 using strings in #fff or #ffffff format:

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

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 colors setting or setColors method.

`openChat`

BrevoConversations('openChat'[, focus])

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

Bear in mind that expanded chat window occupies the whole screen on mobile devices. If this is not the desired behaviour, use expandWidget method instead.

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

`expandWidget`

BrevoConversations('expandWidget'[, focus])

Expands the chat window. Doesn’t affect mobile devices.

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

focus – optional flag. If set to true chat input field will be 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 startHidden setting.

`show`

BrevoConversations('show')

Shows the widget hidden by 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 requiring a full page load, use this method to track these views and see them in the Conversations’ right pane.

Conversations tracks “regular” views automatically, meaning you don’t have to track them manually. But even if you do call the method right after page load, it won’t generate a duplicate view—Conversations will ignore the call if both the URL and the page title don’t change.

`updateIntegrationData`

BrevoConversations('updateIntegrationData', data)

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

Updates visitor’s info in Conversations’ right pane. null is used to remove properties:

BrevoConversations('updateIntegrationData', {
    email: '[email protected]', /* e-mail changed */
    firstName: 'John', /* first name changed */
    lastName: 'Doe', /* last name changed */
    phone: null, /* phone number removed */
    notes: 'Looking for courage...', /* notes property created */

    /* any number of custom properties */
    'trip wish list': 'Going to Oz with friends'
});

If custom properties set in updateIntegrationData match existing contact attributes, they will be synced in your Contacts database. If not, they will be available in Conversations only.

📘
Any tech-savvy person can change the data identifying them sent to Conversations using JS API. Therefore, any data sent to Conversations using JS API must be considered as auxiliary information, not as a method of unambiguous user identification.

`setLocale`

BrevoConversations('setLocale', localeModifier)

localeModifier – object containing a modified locale structure.

Allows to change any number of the default locale strings. Change the ones you don’t like or all of them to translate the widget to an unsupported language.

See “Translating the widget” for details.

Example:

BrevoConversations('setLocale', {
    chat: {
        input: {
            placeholder: 'Scrivi un messaggio...'
        }
    },
    contactAttributes: {
        firstName: 'Nome',
        lastName: 'Cognome',
    },
    messageTypes: {
        joinedFirst: 'entrato in chat',
        joined: '{{#username}} entrato in chat',
        agentsOffline: 'Operatore Offline'
    }
});

You can also modify locale using locale setting.

`setGroupId`

BrevoConversations('setGroupId', groupId)

Sets agent group ID. Chats started with specified group ID will be assigned to this group.

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

Use null to reset group ID:

BrevoConversations('setGroupId', null);

You can also set agent group ID using groupId setting.

`restart`

BrevoConversations('restart')

Restarts Brevo Conversations.

Use it to update Brevo Conversations settings that can’t be updated using API methods, e.g.

// Update the settings
window.BrevoConversationsSetup = {
    language: 'fr'
};

// Restart Brevo Conversations
BrevoConversations('restart');

`kill`

BrevoConversations('kill')

Removes Brevo Conversations completely from the page. You can call BrevoConversations('restart') to reinitialize Brevo Conversations.

Updated 3 months ago