BotStar Livechat API
Introduction
BotStar's Website Chat Plugin ("widget" for short) provides the easiest way for your website to open an engagement channel with your visitor.
Installation
To make the widget to appear on your web app, simply copy and paste the snippet below before the tag on every page where you want the widget to appear for website visitors.
var BotStar = {appId: "APP_ID"};!function(t,a){var e=function(){(e.q=e.q||[]).push(arguments)};e.q=e.q||[],t.BotStarApi=e;!function(){var t=a.createElement("script");t.type="text/javascript",t.async=1,t.src="https://widget.botstar.com/static/js/widget.js";var e=a.getElementsByTagName("script")[0];e.parentNode.insertBefore(t,e)}();}(window,document);
Widget Initial Configuration
The widget has some behaviors when setup:
user
: the widget will load the existing user byuser_id
and update user attributes. Ifuser_id
is not provided or the widget can not find user by thatuser_id
, it will create the new one with provided user attributes. Learn more about available attributes in User Data Attributes section.variables
: the widget will update user's variables. Learn more about variables.block
: the widget will get the start message for conversation by provided block ID. You can see the block ID by clicking the and the ID field is in the Properties Panel.
var BotStar = {appId: "APP_ID", // requiredmode: "livechat",user: {user_id: "UNIQUE_USER_ID",email: "your@user.email",first_name: "Foo",last_name: "Bar",another_attribute: "New value"},variables: {product_name: "The Witcher",product_price: 3},block: "any-block-id-in-your-chatbot-flow"};
Widget Appearance Configuration
Once you have installed widget on your site, you should see the launcher in the bottom right of your screen.
Now, you might want to tailor how the widget appears on your site by changing the mode
attribute.
var BotStar = {appId: "APP_ID", // requiredmode: "livechat" // optional: "popup" | "inline" | "fullpage"};
Inline Mode
Inline mode requires one specific HTML element to appear on your page.
By default, the element .chatbot-container
will try to take up available space of its HTML parent element.
You can also specify fixed height to the .chatbot-container
element, example:
<div class="chatbot-container" style="height: 100%"></div>
<div class="chatbot-container" style="height: 500px"></div>
JavaScript API
Record Website Audience: In order to use JavaScript API, please disable Enable Guest User in your Connect's Website settings.
Methods
BotStarApi('boot')
var new_botstar_settings = {appId: "APP_ID"};BotStarApi('boot', new_botstar_settings);
This will reinitialize widget with provided data. Learn more about available initial data options.
BotStarApi('open')
BotStarApi('open');
This will show the chat window.
ⓘ This method only available to widget configured with mode of livechat or popup.
BotStarApi('close')
BotStarApi('close');
This will hide the chat window if it is open. It will not hide the widget launcher.
ⓘ This method only available to widget configured with mode of livechat or popup.
BotStarApi('update', updateData)
BotStarApi('update', {user_id: "UNIQUE_USER_ID",first_name: "Foo",last_name: "Boo",email: "your@user.email"});
Calling the update method with a JSON object of user details will update those fields on the current user.
Learn more about available attributes in updateData
in User Data Attributes section.
ⓘ Update Throttling
You can call
BotStarApi('update')
without getting throttled up to 20 times per 30 minutes. After the 20th call, you'll be throttled and the quota of 20 calls will get reset every 30 minutes. Reloading the page will refresh this state.
BotStarApi('onOpen', onOpenListener)
BotStarApi('onOpen', function () {// Do something when chat window opened});
When we show the chat window, you can hook into the event. This requires a function argument.
BotStarApi('onClose', onCloseListener)
BotStarApi('onClose', function () {// Do something when chat window closed});
When we hide the chat window, you can hook into the event. This requires a function argument.
Attributes
Configuration Attributes
Attribute | Type | Description |
---|---|---|
appId | string | Your bot's ID |
mode | string | Display mode |
user | object | User Data Attributes |
variables | object | Object property's value should be string or number only |
block | string | The message ID in your chatbot flow |
User Data Attributes
Attribute | Type | Description |
---|---|---|
user_id | string | Unique ID for your user |
email | string | Associated email on your user account |
first_name | string | Specific your user's first name |
last_name | string | Specific your user's last name |
gender | string | Specific your user's gender. Optional: "male" , "female" , "" |
birthday | string | Specific your user's birthday. Use YYYY-MM-DD format |
avatar | string | Avatar/profile image of your user |
tags | array of string | Additional tag for your user. Notice: it will replace current tags of chat user in BotStar record |
Custom User Attributes
You can also include pre-defined attributes from "Manage User Attributes" in your bot's Audience page, respectively.
If you have any concerns, please feel free to leave a comment below or contact us through support@botstar.com. For more details on how we have helped our customers grow their business, you can view our use cases, blogs or join our BotStar community to learn and share new things 😊