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
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
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
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
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
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
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
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
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
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
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
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
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
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
mode
String
Conversations display mode:
'widget'
— default widget,'frame'
— Conversations is embedded into the block specified ininjectTo
.
Example:
<script>
window.SibConversationsSetup = {
mode: 'frame',
injectTo: 'conversations-wrapper'
};
</script>
<!-- Sendinblue Conversations widget code -->
injectTo
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
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
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
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
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
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
onAnalyticEvent
Function
A callback function that is called every time one of the analytic events listed below happens.
Events not initiated by visitors have a non-interaction flag. Google Analytics doesn't include these events when calculating the bounce rate in statistics.
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” 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 was shown to a visitor.
Pre-chat form submitted
Contact form was submitted by a visitor.
Bot scenario shown
(non-interaction event)
Chatbot scenario was shown to a visitor.
Bot scenario started by visitor
A visitor started a chatbot scenario.
Bot reply option clicked
A visitor clicked on a reply option in a chatbot 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
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
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
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');
startBotScenario
startBotScenario
SibConversations('startBotScenario', scenarioId)
scenarioId
– scenario ID. It can be found on scenario’s page.
Start a chatbot scenario.
Example:
SibConversations('startBotScenario', 'V3RYmUCHcUt3D0g3');
setButtonPosition
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
resetButtonPosition
SibConversations('resetButtonPosition')
- Resets chat button position to the one specified in Sendinblue Conversations Settings.
setButtonSize
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
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
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
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
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
resetColors
SibConversations('resetColors')
Resets the colors set with colors
setting or setColors
method.
openChat
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
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
minimizeWidget
SibConversations('minimizeWidget')
Minimizes the chat window.
hide
hide
SibConversations('hide')
Hides the widget. You can also hide the widget using startHidden
setting.
show
show
SibConversations('show')
Shows the widget hidden by startHidden
setting or hide
method.
pageView
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
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 */
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
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
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
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
kill
SibConversations('kill')
Removes Sendinblue Conversations completely from the page. You can call SibConversations('restart')
to reinitialize Sendinblue Conversations.
Updated 7 days ago