> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

## Basic customization

### Open the widget by clicking on a button

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

Or create a link with the address `#brevoConversationsExpanded`:

```html
<!-- Link anywhere on the page -->
<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:

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

<!-- Brevo Conversations widget code -->
```

Then add this selector to any element on the page:

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

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

<!-- Brevo Conversations widget code -->
```

### Change the widget’s z-index

Use the [`zIndex`](/docs/javascript-api-reference#zindex) setting to update the default z-index (set to `9999`):

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

<!-- Brevo Conversations widget code -->
```

*See also the [`setZIndex` method](/docs/javascript-api-reference#setzindex).*

### Change the chat button colors

Specify the colors **before** the widget code:

```html
<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](https://www.google.com/search?q=hex+color+picker) to generate hex color codes.*

### Change the chat button position based on the screen width

```html
<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 is always positioned at the bottom of the screen. The "round" button uses the same position on both desktop and mobile devices.

### Embed the widget into a block

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

```html
<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](/docs/javascript-api-reference#injectto).*

Place the block anywhere on the page:

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

Then set an appropriate block size, for example:

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

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

<!-- Brevo Conversations widget code -->
```

*Alternatively, uncheck the "Mobile button" option in your [widget settings](https://conversations-app.brevo.com/settings/integrations/widget).*

## Identifying existing users

### Passing user details to Conversations

Use the [`updateIntegrationData`](/docs/javascript-api-reference#updateintegrationdata) method to update the visitor's details in Conversation's right pane. Use `null` to remove properties.

```javascript
/* Anywhere after Brevo Conversations widget code */
BrevoConversations('updateIntegrationData', {
    email: 'cowardly_lion@yahoo.com', /* 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 sync with your [Contacts](https://app.brevo.com/contact/list) database. Otherwise, they're available in Conversations only.

**Any tech-savvy user can modify the identification data sent to Conversations via the JS API.** Treat data sent through the JS API as auxiliary information, not as a definitive user identifier.

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

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

   <!-- 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](https://conversations-app.brevo.com/settings/integrations/widget), and use the JavaScript API for more granular control (see the [`language`](/docs/javascript-api-reference#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`](https://conversations-widget.brevo.com/locale.json)

To change the chat input placeholder text:

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

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

```html
<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. Strings with keys starting with `_` are protected and cannot be changed.

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

```javascript
/* Anywhere after Brevo Conversations widget code */

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