Customize the chat widget

Simple customizing

Open the widget by clicking on a button

<!-- Custom button anywhere on the page -->
<button onclick="BrevoConversations('openChat', true)">Chat with us</button>

Or you can create a link with the address #brevoConversationsExpanded:

<!-- Link anywhere on the page -->
<a href="#brevoConversationsExpanded">Chat with us</a>

Also, you can use 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). The first step is to place the following snippet before the main widget code:

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

<!-- Brevo Conversations widget code -->

Then add this selector to any element on the page:

<!-- Custom button anywhere on the page -->
<button class="custom-chat-button">Chat with us</button>

Change the widget’s width and height

Specify chatWidth and chatHeight (in pixels) before the widget code:

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

<!-- Brevo Conversations widget code -->

Change the widget’s z-index

Use the zIndex setting to update the default z-index (set to 9999):

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

<!-- Brevo Conversations widget code -->

See also the setZIndex method.

Change the chat button colors

Specify the colors before the widget code:

<script>
    window.BrevoConversationsSetup = {
        colors: {
            buttonText: '#f0f0f0', /* chat button text color */
            buttonBg: '#565656'    /* chat button background color */
        }
    };
</script>

<!-- Brevo Conversations widget code -->

Use a color picker to generate hex color codes.

Change the chat button position based on the screen width

<script>
window.BrevoConversationsSetup = {
    buttonPosition: window.innerWidth < 1024 ? /* width threshold */
        'bl' : /* chat button position on small screens */
        'br'  /* chat button position on big screens */
};
</script>

<!-- Brevo Conversations widget code -->

Use the following codes to set the chat button position:

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

Embed the widget into a block

Specify id of the block you want to embed the chat widget into before the widget code:

<script>
window.BrevoConversationsSetup = {
    mode: 'frame',
    /* id of the block you want to embed chat into */
    injectTo: 'conversations-wrapper'
};
</script>

<!-- Brevo Conversations widget code -->

injectTo also accepts direct links to HTML nodes and array-like node collections (including NodeLists and jQuery collections). See injectTo description.

Place the block anywhere on the page:

<div id="conversations-wrapper"></div>

The only thing left is to set an appropriate block size, e.g.

<div id="conversations-wrapper" style="width: 100%; height: 500px;"></div>

Conversations will occupy the whole block.

Disable Conversations on mobile devices

Insert this code before the widget code:

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

<!-- Brevo Conversations widget code -->

Or look for “Mobile button” option in your widget settings and uncheck it.

Identifying existing users

Passing user details to Conversations

Use the updateIntegrationData method to update the visitor's details in Conversation's right pane. Use null to remove properties.

/* Anywhere after Brevo Conversations widget code */
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.

Binding conversations to user accounts

Conversations can recognize logged-in users regardless of the device or browser they use, so that a single conversation thread will be maintained. Also, if the user logs out and another logs in on the same device, the two different conversation threads will be kept separated.

To bind the widget to user accounts on your site:

Generate a unique random string for each user and save it to your database.

When the user is logged in, specify their string before the widget code like this:

<script>
window.BrevoConversationsSetup = {
    /* current user’s generated string */
    visitorId: 'kZMvWhf8npAu3H6qd57w2Hv6nh6rnxvg'
};
</script>

<!-- Brevo Conversations widget code -->

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

Translating the widget

You can choose the widget language from Conversations’ settings and use Javascript API for more granular control (see language setting).

If the desired language is not supported or you wish to change some of the strings of an existing language, you can override one of the existing languages with your set of strings.

❗
Note, that adding unsupported languages as new properties to the locale object ("fi", "sv", "pl" etc.) is not possible.

Here’s our current locale file:
locale.json

Let’s say you want to change chat input placeholder text. Here’s how you can do it:

<script>
window.BrevoConversationsSetup = {
    locale: {
        chat: {
            input: {
                placeholder: 'Meddelande...'
            }
        }
    }
};
</script>

<!-- Brevo Conversations widget code -->

To change more strings, just add all of them to the locale property of BrevoConversationsSetup (adhere to the structure of the original locale file). If the language code key is not specified, phrases will be changed in all language versions.

<script>
window.BrevoConversationsSetup = {
    locale: {
        chat: {
            input: {
                placeholder: {
                    en: 'Message...',
                    /* overriding only the French phrase with the Swedish translation */
                    fr: 'Meddelande...'
                }
            }
        },
        contactAttributes: {
            firstName: 'Namn',
            lastName: 'Efternamn',
        },
        messageTypes: {
            joinedFirst: 'ansluten,
            joined: '{{#username}} anslöt',
            agentsOffline: 'Agents är offline'
        }
    }
};
</script>

<!-- Brevo Conversations widget code -->

You can change as many strings as you want. Bear in mind that strings with keys starting with _ are protected from changing.

You can also change the locale dynamically using setLocale method:

/* Anywhere after Brevo Conversations widget code */

BrevoConversations('setLocale', {
    chat: {
        input: {
            placeholder: 'Meddelande...'
        }
    }
});