Javascript API reference

Settings

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

<script>
window.SibConversationsSetup = {
    chatHeight: 350,
    colors: {
        buttonText: '#f600a5',
        buttonBg: '#fff'
    },
    startHidden: true
};
</script>

<!-- Sendinblue Conversations widget code -->

buttonStyle

String

Chat button style. Overrides the style set in widget settings. Possible values:

• 'tab'
• 'round'

Example:

<script>
window.SibConversationsSetup = {
    buttonStyle: 'round'
};
</script>

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

<script>
window.SibConversationsSetup = {
    buttonPosition: 'bl'
};
</script>

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

<script>
window.SibConversationsSetup = {
    buttonSize: 75
};
</script>

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

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

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

<script>
window.SibConversationsSetup = {
    chatWidth: 280
};
</script>

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

<script>
window.SibConversationsSetup = {
    chatHeight: 400
};
</script>

<!-- Sendinblue Conversations widget code -->

zIndex

Number

Chat widget’s z-index value, default is 9999. You can also change z-index using setZIndex method.

Example:

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

<!-- Sendinblue Conversations widget code -->

colors

Object

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

<script>
window.SibConversationsSetup = {
    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>

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

<script>
window.SibConversationsSetup = {
    startHidden: true
};
</script>

<!-- Sendinblue Conversations widget code -->

mobileOnly

Boolean

If set to true the widget will show up only on mobile devices.

Example:

<script>
window.SibConversationsSetup = {
    mobileOnly: true
};
</script>

<!-- Sendinblue Conversations widget code -->

disabledOnMobile

Boolean

If set to true the widget won’t show up on mobile devices.

Example:

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

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

<script>
window.SibConversationsSetup = {
    language: 'fr'
};
</script>

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

<script>
window.SibConversationsSetup = {
    locale: {
        chat: {
            input: {
                placeholder: 'Scrivi un messaggio...'
            }
        },
        name: 'Nome',
        yourName: 'Il tuo nome',
        messageTypes: {
            joinedFirst: 'entrato in chat',
            joined: '{{#username}} entrato in chat',
            agentsOffline: 'Operatore Offline'
        }
    }
};
</script>

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

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

<!-- Sendinblue Conversations widget code -->

injectTo

String | Array | Object

Specifies the element Sendinblue 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:

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

<!-- Sendinblue Conversations widget code -->

If you are using an HTML node or a collection, make sure it’s possible to receive required element when SibConversationsSetup 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:

<script>
    window.SibConversationsSetup = {
        visitorId: 'kZMvWhf8npAu3H6qd57w2Hv6nh6rnxvg'
    };
</script>

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

<script>
    window.SibConversationsSetup = {
        groupId: 'z2o3F8GDkNpKD4BYt'
    };
</script>

<!-- Sendinblue 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 Sendinblue Conversations events to.

There’s no need to set this unless you have several GA trackers in use on the same page. Sendinblue Conversations sends events to Google Analytics automatically using the first GA tracker it can find on the page.

Example:

<script>
    window.SibConversationsSetup = {
        gaTrackingId: 'UA-12345678-1'
    };
</script>

<!-- Sendinblue Conversations widget code -->

disableGaTracking

Boolean

Set this option to true to prevent Sendinblue Conversations from sending events to Google Analytics.

Example:

<script>
    window.SibConversationsSetup = {
        disableGaTracking: true
    };
</script>

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

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

<!-- Sendinblue Conversations widget code -->

The message object includes the following keys:

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

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 following analytic events happens:

Chat initiated by visitor
    A visitor initiated the chat by sending a message

Chat initiated by agent
    An agent initiated the chat by writing a message in the existing conversation after a period of inactivity

Chat accepted by agent
    An agent replied to a new chat from a visitor

Targeted chat shown
    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
    Contact form was shown to a visitor

Pre-chat form submitted
    Contact form was submitted by a visitor

Bot scenario shown
    Chat bot scenario was shown to a visitor

Bot scenario started by visitor
    A visitor started a chat bot scenario

Bot reply option clicked
    A visitor clicked on a reply option in a chat bot scenario

The function receives event name as an argument:

<script>
    window.SibConversationsSetup = {
        onAnalyticEvent: function(eventName) {
            console.log('An event just happend:', eventName);
        }
    };
</script>

<!-- Sendinblue Conversations widget code -->

Sendinblue Conversations sends these events to Google Analytics automatically. Use this setting to pass Sendinblue 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:

<script>
    window.SibConversationsSetup = {
        deferredLoading: true
    };
</script>

<!-- Sendinblue Conversations widget code -->

disableChatOpenHash

Boolean

When a visitor opens a chat window on mobile devices, #sibConversationsExpanded 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:

<script>
    window.SibConversationsSetup = {
        disableChatOpenHash: true
    };
</script>

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

<!-- Sendinblue Conversations widget code -->

<script>
    SibConversations('expandWidget');
</script>

All method calls made before Sendinblue Conversations finished loading are put into a queue and executed when Sendinblue Conversations is ready.

sendAutoMessage

SibConversations('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:

SibConversations('sendAutoMessage', 'Hi there 👋 Chat with us if you need a hand');

setButtonPosition

SibConversations('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

SibConversations('resetButtonPosition')

• Resets chat button position to the one specified in Sendinblue Conversations Settings.

setButtonSize

SibConversations('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

SibConversations('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

SibConversations('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

SibConversations('setZIndex', zIndex)

zIndex – integer, default is 9999.

Sets chat widget’s z-index value. You can also set z-index using zIndex setting.

setColors

SibConversations('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:

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

SibConversations('resetColors')

Resets the colors set with colors setting or setColors method.

openChat

SibConversations('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

SibConversations('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

SibConversations('minimizeWidget')

Minimizes the chat window.

hide

SibConversations('hide')

Hides the widget. You can also hide the widget using startHidden setting.

show

SibConversations('show')

Shows the widget hidden by startHidden setting or hide method.

pageView

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

Conversations tracks “regular” views automatically, meaning you don’t have to track them manually. But even if you do call the method right after page load, it won’t generate a duplicate view—Conversations will ignore the call if both the URL and the page title don’t change.

updateIntegrationData

SibConversations('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:

SibConversations('updateIntegrationData', {
    email: '[email protected]', /* e-mail changed */
    firstName: 'John', /* first name changed */
    lastName: 'Doe', /* last name changed */
    email: '[email protected]', /* e-mail 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.

setLocale

SibConversations('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:

SibConversations('setLocale', {
    chat: {
        input: {
            placeholder: 'Scrivi un messaggio...'
        }
    },
    name: 'Nome',
    yourName: 'Il tuo nome',
    messageTypes: {
        joinedFirst: 'entrato in chat',
        joined: '{{#username}} entrato in chat',
        agentsOffline: 'Operatore Offline'
    }
});

You can also modify locale using locale setting.

setGroupId

SibConversations('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:

SibConversations('setGroupId', null);

You can also set agent group ID using groupId setting.

restart

SibConversations('restart')

Restarts Sendinblue Conversations.

Use it to update Sendinblue Conversations settings that can’t be updated using API methods, e.g.

// Update the settings
window.SibConversationsSetup = {
    language: 'fr'
};

// Restart Sendinblue Conversations
SibConversations('restart');

kill

SibConversations('kill')

Removes Sendinblue Conversations completely from the page. You can call SibConversations('restart') to reinitialize Sendinblue Conversations.