Web SDK
If you would like to see any of the Roadmap features, something else or have feedback on the existing API, reach out to liam@botbrains.io. $botbrains.
The SDK is shipped by default and the API will be expanded based on user needs. See Roadmap.
Prerequisite
The SDK is NOT supported if you use the deprecated iFrame integration. Use the launcher and benefit from all new features.
<script type="text/javascript">
$botbrains = [];
$botbrains.push(["set", "config", {
frameId: 'YOUR_FRAME_ID',
}]);
(function(){d = document;s = d.createElement('script');s.src = 'https://chat.botbrains.io/loader.js';s.type = 'module';s.async = 1;d.getElementsByTagName('head')[0].appendChild(s);})();
</script>
Use Cases
Hide Launcher on specific pages
// Check if the current page matches a specific URL
if (window.location.pathname === "/specific-page") {
$botbrains.push(["do", "chat.hide"]);
}
Hide Launcher on small devices
// Check the screen width and hide the launcher if the width is below a threshold (e.g., 600px)
if (window.innerWidth < 600) {
$botbrains.push(["do", "chat.hide"]);
}
<button
onclick="$botbrains.push(['do', 'message.send', 'How does Feature XY work?'])"
>
Get Help
</button>
Annotate User Data
const data = {
first_name: "Liam",
last_name: "van der Viven",
email: "liam@botbrains.io",
phone: "+4915168433056",
external_attributes: {
"plan": "business",
}
};
$botbrains.push(["set", "user.data", data]);
Identify Users
We also support identifying users against our system. Please talk to liam@botbrains.io for get an introduction.
Change the suggestions
if (window.location.pathname === "/product-abc")
$botbrains.push(["set", "chat.suggestions", ["What ROI did customers see with ABC?", "Does ABC have regional hosting?", "Can I get a demo of ABC?"]])
Docs
You can then use the $botbrains object via .push immediately below adding our script.
.push allows you to call .do .set .on and .off safely.
If you need .is or .on, store a callback in window.BOTBRAINS_ON_LOADED.
.is to branch your code based on our state.do to trigger actions, don’t return values.set to modify state, annotate users and more.on and .off for registering/unregistering callbacks.get returns a Promise
On a page that has botBrains loaded, you can open the Developer Console and use $botbrains.help() to see all command names.
Commands
do-Commands are by default async and do not return anything. This allows you to call them at any point, even before the SDK is ready.
// Handle Visibility of complete system
$botbrains.push(["do", "chat.show"]);
$botbrains.push(["do", "chat.hide"]);
// Expand Chat
$botbrains.push(["do", "chat.open"]);
$botbrains.push(["do", "chat.close"]);
$botbrains.push(["do", "chat.toggle"]);
// Change Position
$botbrains.push(["set", "chat.side", "left"]); // or 'right'
$botbrains.push(["set", "chat.marginSide", "20px"]); // or '10rem' or '10vw' or ...
$botbrains.push(["set", "chat.marginBottom", "20px"]); // ...
// Only if Previews are enabled, you can manually control them
$botbrains.push(["set", "preview.show"])
$botbrains.push(["set", "preview.hide"])
// Setting custom message tags
$botbrains.push(["set", "message.tags", [["Name", "Value"]]]);
// Prefill the message box
$botbrains.push(["set", "message.text", "Hi, how does product XY work?"]);
// Send the current message box
$botbrains.push(["do", "message.send"]);
// Combined: Prefill and send question immediately
$botbrains.push(["do", "message.send", "Hi, how does product XY work?"]);
Conditionals
// Check if the other commands are available
$botbrains.is("chat.ready");
$botbrains.is("chat.visible");
$botbrains.is("chat.opened");
$botbrains.is("preview.visible");
Personalization - Theme and Localization
By default, we will auto-match user preferences and choose the most fitting value. You can manually control them.
// Theme - defaults to user preference; values are "light"|"dark"|"auto"
$botbrains.push(["set", "config.theme", "dark"]);
// Locale - defaults to user preference; Values must be in BCP 47 'de' or 'de-CH'
$botbrains.push(["set", "config.locale", "de-CH"]);
Events
// You can register and unregister functions with the same identity to run on a event.
// Callbacks take a single payload argument.
$botbrains.push(["on", event, callback]);
$botbrains.push(["off", event, callback]);
// Example
$botbrains.push(["on", "config.loaded", (config) => console.log(config)]);
chat.readyframe.loadedchat.openedchat.closed
Users
Data
You can annotate user data and additional arbitrary JSON under external_attributes upto 8 KB.
$botbrains.push(["set", "user.data", {
first_name: "Liam",
last_name: "van der Viven",
email: "liam@botbrains.io",
phone: "+4915168433056",
external_attributes: {
plan: "business",
joined_on: "2024-04-09"
}
}]);
Identify
You can also identify users, which enables cross device session continuity by setting an external_id. Be careful, external_id may only be set once. Two users with the same external_id will be able to read messages of the other user. Please check your implementation by reading our Complete Guide to Users or talking to ben@botbrains.io.
$botbrains.push(["do", "user.identify", ["user_58066af9-eae5-4315-99e7-967993f43c07", {
first_name: "Liam",
// ... properties that are also supported by user.data
}]]);
Debugging
If you have issues, enable verbose logs with window.BOTBRAINS_DEBUG = true or ?botbrainsDebug=true in the URL.
Roadmap
There are many ways we could expand the API to control more parts of the Chat.
Missing something? Let us know what you would like to see, support@botbrains.io.
Frequently Asked Questions
Coming soon.
