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

## Settings

Settings are defined via the `window.BrevoConversationsSetup` object **before** the widget code, for example:

```html
<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](https://conversations-app.brevo.com/settings/integrations/widget). Possible values:

* `'tab'`
* `'round'`

Example:

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

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

### `buttonPosition`

*String*

Chat button position. Overrides the position set in [widget settings](https://conversations-app.brevo.com/settings/integrations/widget). 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 is always positioned at the bottom of the screen. The "round" button uses the same position on both desktop and mobile devices.

Example:

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

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

You can also change the position using [`setButtonPosition`](#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 the [`setButtonSize`](#setbuttonsize) method.

Example:

```html
<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 an element of your choice. This also hides the default chat button. Set this **before** the widget code.

Example:

```html
<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 the [`setChatWidth`](#setchatwidth) method.

Example:

```html
<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 the [`setChatHeight`](#setchatheight) method.

Example:

```html
<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 the `z-index` using the [`setZIndex`](#setzindex) method.

Example:

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

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

### `colors`

[](#colors)

*Object*

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

```html
<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](https://caniuse.com/#feat=css-variables). Browsers without CSS variable support display default colors.

You can also change the color scheme of the widget using the [`setColors`](#setcolors) method.

### `startHidden`

*Boolean*

If set to `true`, the widget starts hidden. You can also show and hide the widget using the [`show`](#show) and [`hide`](#hide) methods.

Example:

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

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

### `mobileOnly`

*Boolean*

If set to `true`, the widget appears only on mobile devices.

Example:

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

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

### `disabledOnMobile`

*Boolean*

If set to `true`, the widget doesn't appear on mobile devices.

Example:

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

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

### `language`

*String*

Widget language. Overrides the language set in [widget settings](https://conversations-app.brevo.com/settings/integrations/widget). Possible values: `'en'`, `'de'`, `'fr'`, `'es'`, `'nl'`, `'pt'`, `'it'`, and `'ru'`.

Example:

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

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

### `locale`

*Object*

Lets you change any number of the [default locale](https://conversations-widget.brevo.com/locale.json) strings. Override individual strings, or all of them to translate the widget into an unsupported language.

See [Translating the widget](/docs/customize-the-widget#translating-the-widget) for details.

Example:

```html
<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 the locale dynamically using the [`setLocale`](#setlocale) method.

### `mode`

*String*

Conversations display mode:

* `'widget'` — default widget,
* `'frame'` — Conversations is embedded into the block specified in [`injectTo`](#injectto).

Example:

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

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

### `injectTo`

*String* | *Array* | *Object*

Specifies the element Brevo Conversations is embedded into when launched in `frame` mode (see [`mode`](#mode)). Possible values: the element's `id`, a direct link to the HTML Node, or an array-like HTML Node collection, including NodeLists and jQuery collections (the first element of the collection is used).

Example:

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

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

*If you use an **HTML node** or a **collection**, ensure the required element is available when the `BrevoConversationsSetup` object is defined (place the definition before the closing `</body>` tag or run it after the `DOMContentLoaded` event). If you specify the element's `id` instead, Conversations searches for the element automatically after the `DOMContentLoaded` event.*

### `visitorId`

*String*

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

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

See [Binding conversations to user accounts](/docs/customize-the-widget#binding-conversations-to-user-accounts).

Example:

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

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

### `groupId`

*String*

Agent group ID. Chats started on a page with this group ID set are assigned to this group. You can find the group's ID on its page in Conversations' ["Groups" settings](https://conversations-app.brevo.com/settings/groups).

Example:

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

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

You can also change the agent group ID using the [`setGroupId`](#setgroupid) method.

### `gaTrackingId`

*String*

Sets a specific Google Analytics tracking ID to send Brevo Conversations events to.

**You only need to set this if you have several GA trackers on the same page.** Otherwise, Brevo Conversations sends events to Google Analytics automatically using the first GA tracker it finds on the page.

Example:

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

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

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

### `onNewMessage`

*Function*

A callback function called every time a new message arrives.

The function receives the message details as an argument:

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

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

The `message` object includes the following keys:

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

`id` — message ID. Used for further operations on 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 called every time one of the analytic events listed below occurs.\
Events not initiated by visitors have a non-interaction flag. Google Analytics excludes these events when calculating the bounce rate.

`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”](https://conversations-app.brevo.com/settings/actions) 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](https://conversations-app.brevo.com/settings/bot) was shown to a visitor.

`Pre-chat form submitted`\
     [Contact form](https://conversations-app.brevo.com/settings/bot) was submitted by a visitor.

`Bot scenario shown` (non-interaction event)\
     [Chatbot scenario](https://conversations-app.brevo.com/settings/bot) was shown to a visitor.

`Bot scenario started by visitor`\
     A visitor started a [chatbot scenario](https://conversations-app.brevo.com/settings/bot).

`Bot reply option clicked`\
     A visitor clicked on a reply option in a [chatbot scenario](https://conversations-app.brevo.com/settings/bot).

The function receives event name as an argument:

```html
<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 finished loading.

This may improve your score in tools like [PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/), but the chat button takes longer to appear.

Example:

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

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

### `disableChatOpenHash`

*Boolean*

When a visitor opens a chat window on a mobile device, `#brevoConversationsExpanded` is added to the page address. This lets the visitor 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 the behavior:

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

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

## Methods

Methods dynamically change the behavior of the chat widget. Call them anywhere after the widget code, for example:

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

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

Method calls made before Brevo Conversations finishes loading are queued and executed once 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 the same way as [automatic targeted messages](https://conversations-app.brevo.com/settings/actions), but lets you define custom logic and control what is sent and when.

Example:

```javascript
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](https://conversations-app.brevo.com/settings/groups). 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:

```javascript
BrevoConversations('sendVisitorMessage', 'I need help with my order');
```

### `startBotScenario`

`BrevoConversations('startBotScenario', scenarioId)`

`scenarioId` – scenario ID, found on the scenario's page.

Starts a [chatbot scenario](https://conversations-app.brevo.com/settings/scripts).

Example:

```javascript
BrevoConversations('startBotScenario', 'V3RYmUCHcUt3D0g3');
```

### `setButtonPosition`

`BrevoConversations('setButtonPosition', positionCode)`

Sets the chat button position. Overrides the position set in [widget settings](https://conversations-app.brevo.com/settings/integrations/widget).

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

You can also set the position using the [`buttonPosition`](#buttonposition) setting.

### `resetButtonPosition`

`BrevoConversations('resetButtonPosition')`

* Resets the chat button position to the one specified in [Brevo Conversations Settings](https://conversations-app.brevo.com/settings/integrations/widget).

### `setButtonSize`

`BrevoConversations('setButtonSize', size)`

`size` – positive integer, default is `60`.

Sets the size of the round chat button in `px`. Does not affect the "tab" button. You can also set the round chat button size using the [`buttonSize`](#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 the [`chatWidth`](#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 the [`chatHeight`](#chatheight) setting.

### `setZIndex`

`BrevoConversations('setZIndex', zIndex)`

`zIndex` – integer, default is `9999`.

Sets the chat widget's `z-index` value. You can also set `z-index` using the [`zIndex`](#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 as strings in `#fff` or `#ffffff` format:

```javascript
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](https://caniuse.com/#feat=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`](#colors) setting.

### `resetColors`

`BrevoConversations('resetColors')`

Resets the colors set with the [`colors`](#colors) setting or [`setColors`](#setcolors) method.

### `openChat`

`BrevoConversations('openChat'[, focus])`

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

The expanded chat window occupies the entire screen on mobile devices. If that isn't what you want, use the [`expandWidget`](#expandwidget) method instead.

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

### `expandWidget`

`BrevoConversations('expandWidget'[, focus])`

Expands the chat window. Has no effect on mobile devices.

To expand the chat window on both desktop and mobile devices, use the [`openChat`](#openchat) method instead.

`focus` – optional flag. If set to `true`, the chat input field is 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 the [`startHidden`](#starthidden) setting.

### `show`

`BrevoConversations('show')`

Shows the widget hidden by the [`startHidden`](#starthidden) setting or [`hide`](#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 a full page load, use this method to track these views in the Conversations right pane.

Conversations tracks "regular" views automatically, so you don't need to track them manually. Even if you call this method right after page load, it won't create a duplicate view—Conversations ignores the call if neither the URL nor the page title changed.

### `updateIntegrationData`

`BrevoConversations('updateIntegrationData', data)`

`data` — object containing any number of properties. Each property's value must be a *String*, *Number*, *Boolean*, or `null`.

Updates the visitor's info in the Conversations right pane. Use `null` to remove properties:

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

### `setLocale`

`BrevoConversations('setLocale', localeModifier)`

`localeModifier` – object containing a modified locale structure.

Lets you change any number of the [default locale](https://conversations-widget.brevo.com/locale.json) strings. Override individual strings, or all of them to translate the widget into an unsupported language.

See [Translating the widget](/docs/customize-the-widget#translating-the-widget) for details.

Example:

```javascript
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 the locale using the [`locale`](#locale) setting.

### `setGroupId`

`BrevoConversations('setGroupId', groupId)`

Sets the agent group ID. Chats started with this group ID set are assigned to this group.

You can find the group's ID on its page in Conversations' ["Groups" settings](https://conversations-app.brevo.com/settings/groups).

Use `null` to reset the group ID:

```javascript
BrevoConversations('setGroupId', null);
```

You can also set the agent group ID using the [`groupId`](#groupid) setting.

### `restart`

`BrevoConversations('restart')`

Restarts Brevo Conversations.

Use it to update Brevo Conversations settings that can't be updated through [API methods](#methods), for example:

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

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

### `kill`

`BrevoConversations('kill')`

Removes Brevo Conversations completely from the page. Call [`BrevoConversations('restart')`](#restart) to reinitialize Brevo Conversations.