Customize the chat widget

Basic customization

Open the widget by clicking on a button

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

Or create a link with the address #brevoConversationsExpanded:

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

You can also use any valid CSS selector as the customWidgetButton to assign chat button behavior to an element of your choice. This also hides the default chat button. First, place the following snippet before the main widget code:

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

Then add this selector to any element on the page:

1
<!-- Custom button anywhere on the page -->
2
<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:

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

Change the widget’s z-index

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

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

See also the setZIndex method.

Change the chat button colors

Specify the colors before the widget code:

1
<script>
2
    window.BrevoConversationsSetup = {
3
        colors: {
4
            buttonText: '#f0f0f0', /* chat button text color */
5
            buttonBg: '#565656'    /* chat button background color */
6
        }
7
    };
8
</script>
9
10
<!-- Brevo Conversations widget code -->

Use a color picker to generate hex color codes.

Change the chat button position based on the screen width

1
<script>
2
window.BrevoConversationsSetup = {
3
    buttonPosition: window.innerWidth < 1024 ? /* width threshold */
4
        'bl' : /* chat button position on small screens */
5
        'br'  /* chat button position on big screens */
6
};
7
</script>
8
9
<!-- 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

Embed the widget into a block

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

1
<script>
2
window.BrevoConversationsSetup = {
3
    mode: 'frame',
4
    /* id of the block you want to embed chat into */
5
    injectTo: 'conversations-wrapper'
6
};
7
</script>
8
9
<!-- 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:

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

Then set an appropriate block size, for example:

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

Conversations occupies the entire block.

Disable Conversations on mobile devices

Insert this code before the widget code:

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

Alternatively, uncheck the “Mobile button” option in your widget settings.

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.

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

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

Binding conversations to user accounts

Conversations recognizes logged-in users regardless of device or browser, maintaining a single conversation thread per user. If one user logs out and another logs in on the same device, the two conversation threads remain separate.

To bind the widget to user accounts on your site:

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

2. When the user is logged in, specify their string before the widget code:

   1
   <script>
   2
   window.BrevoConversationsSetup = {
   3
       /* current user’s generated string */
   4
       visitorId: 'kZMvWhf8npAu3H6qd57w2Hv6nh6rnxvg'
   5
   };
   6
   </script>
   7
   8
   <!-- Brevo Conversations widget code -->

❗️

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

Translating the widget

Choose the widget language from Conversations’ settings, and use the JavaScript API for more granular control (see the language setting).

If the language you want isn’t supported, or you want to change strings in an existing language, override one of the existing languages with your set of strings.

❗

You cannot add unsupported languages as new properties to the locale object (“fi”, “sv”, “pl”, etc.).

The current locale file:
locale.json

To change the chat input placeholder text:

1
<script>
2
window.BrevoConversationsSetup = {
3
    locale: {
4
        chat: {
5
            input: {
6
                placeholder: 'Meddelande...'
7
            }
8
        }
9
    }
10
};
11
</script>
12
13
<!-- Brevo Conversations widget code -->

To change more strings, add them to the locale property of BrevoConversationsSetup (following the structure of the original locale file). If no language code key is specified, phrases are changed in all language versions.

1
<script>
2
window.BrevoConversationsSetup = {
3
    locale: {
4
        chat: {
5
            input: {
6
                placeholder: {
7
                    en: 'Message...',
8
                    /* overriding only the French phrase with the Swedish translation */
9
                    fr: 'Meddelande...'
10
                }
11
            }
12
        },
13
        contactAttributes: {
14
            firstName: 'Namn',
15
            lastName: 'Efternamn',
16
        },
17
        messageTypes: {
18
            joinedFirst: 'ansluten,
19
            joined: '{{#username}} anslöt',
20
            agentsOffline: 'Agents är offline'
21
        }
22
    }
23
};
24
</script>
25
26
<!-- Brevo Conversations widget code -->

You can change as many strings as you want. Strings with keys starting with _ are protected and cannot be changed.

You can also change the locale dynamically using the setLocale method:

1
/* Anywhere after Brevo Conversations widget code */
2
3
BrevoConversations('setLocale', {
4
    chat: {
5
        input: {
6
            placeholder: 'Meddelande...'
7
        }
8
    }
9
});