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 by user_id and update user attributes. If user_id is not provided or the widget can not find user by that user_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", // required
mode: "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", // required
mode: "livechat" // optional: "popup" | "inline" | "fullpage"
};

Inline Mode

Inline mode requires one specific HTML element to appear on your page. inline mode

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

AttributeTypeDescription
appIdstringYour bot's ID
modestringDisplay mode
userobjectUser Data Attributes
variablesobjectObject property's value should be string or number only
blockstringThe message ID in your chatbot flow

User Data Attributes

AttributeTypeDescription
user_idstringUnique ID for your user
emailstringAssociated email on your user account
first_namestringSpecific your user's first name
last_namestringSpecific your user's last name
genderstringSpecific your user's gender. Optional: "male", "female", ""
birthdaystringSpecific your user's birthday. Use YYYY-MM-DD format
avatarstringAvatar/profile image of your user
tagsarray of stringAdditional 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.

custom attributes

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 😊


Did you find it helpful?   Yes   No