JavaScript API reference

Settings

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

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 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 the element of your choice (this will also hide the default chat button). To be set 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 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 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 z-index using 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 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:

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 will show up 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 won’t show up 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

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:

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 locale dynamically using 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 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:

1
<script>
2
window.BrevoConversationsSetup = {
3
    mode: 'frame',
4
    injectTo: 'conversations-wrapper'
5
};
6
</script>
7
8
<!-- 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:

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

1
<script>
2
    window.BrevoConversationsSetup = {
3
        groupId: 'z2o3F8GDkNpKD4BYt'
4
    };
5
</script>
6
7
<!-- 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:

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 that is called every time when a new message is there.

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

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

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

1
<script>
2
    window.BrevoConversationsSetup = {
3
        disableChatOpenHash: true
4
    };
5
</script>
6
7
<!-- 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:

1
<!-- Brevo Conversations widget code -->
2
3
<script>
4
    BrevoConversations('expandWidget');
5
</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:

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. It can be found on scenario’s page.

Start a chatbot scenario.

Example:

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

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:

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

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:

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 will be synced in your Contacts database. If not, they will be available in Conversations only.

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:

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

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

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. You can call BrevoConversations('restart') to reinitialize Brevo Conversations.