Browse the docs
Widget
JavaScript API
Control the widget from your code with asdk(...) commands: open it, pass signed-in users, track events, listen for leads and change the language.
Last updated
On this page
The widget adds one global function to your pages, asdk. With it, your own code can open the chat from a button, tell the widget who is signed in, react when a visitor leaves their details, and more. Everything here is optional: the widget works without a line of code beyond the snippet.
Call the API before the widget loads
The snippet loads asynchronously, so asdk doesn't exist for the first moments after a page loads. Add this line before the snippet, and calls made early are queued and run in order once the widget is ready:
<script>
window.asdk = window.asdk || function () { (asdk.q = asdk.q || []).push(arguments); };
</script>
<script async src="https://cdn.asdk.com/v1/asdk.js" data-site-id="SITE_ID"></script>Loading the snippet twice on a page is harmless: the second copy notices the first and stops.
Commands
| Command | What it does |
|---|---|
asdk("open") | Opens the chat panel and moves keyboard focus into it |
asdk("close") | Closes the panel |
asdk("toggle") | Opens the panel if it's closed, closes it if it's open |
asdk("identify", { email, name, userId, userHash }) | Tells the widget who the signed-in visitor is |
asdk("track", name, props) | Records a custom event with optional properties |
asdk("on", event, handler) | Calls handler when a widget event happens |
asdk("off", event, handler) | Stops calling handler; without handler, removes all handlers of that event |
asdk("setLocale", "de") | Switches the widget's interface language |
asdk("shutdown") | Removes the widget and forgets the signed-in visitor and the current conversation |
Unknown commands log a warning in the browser console and do nothing.
Events
| Event | When | The handler receives |
|---|---|---|
open | The panel opens | Nothing |
close | The panel closes | Nothing |
message | A visitor sends a message, or an answer finishes | role (visitor or agent), text, messageId, conversationId |
lead | A visitor sends the contact form | leadId, email, name, company, phone, conversationId |
meeting | A visitor clicks a "Book a meeting" button | url |
An error thrown inside your handler doesn't break the widget.
Examples
Open the chat from your own button
<button type="button" onclick="asdk('open')">Talk to us</button>Pass the signed-in user
asdk("identify", { email: user.email, name: user.name, userId: user.id });The details prefill the contact form. To have ASDK store the identity with the conversation, also send a userHash signed by your server; see Identity verification.
Forget the user on logout
asdk("shutdown");Call this when someone signs out on a shared computer: the next person won't see the previous conversation. The anonymous visitor ID is kept.
Send leads to Google Tag Manager
asdk("on", "lead", function (lead) {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({ event: "asdk_lead", leadId: lead.leadId });
});Prefer IDs over email addresses and phone numbers when you pass data to analytics tools.
Record your own events
asdk("track", "pricing_calculator_used", { plan: "pro" });Configure the widget without data attributes
Tag managers can't always add data- attributes to the scripts they insert. Set the same options in window.asdkConfig before the script loads instead:
<script>
window.asdkConfig = { siteId: "SITE_ID", locale: "de", position: "left", open: false };
</script>
<script async src="https://cdn.asdk.com/v1/asdk.js"></script>| Script attribute | asdkConfig key | Values |
|---|---|---|
data-site-id | siteId | Your Site ID. Required. |
data-locale | locale | A language code such as de or pt-BR, or browser. See Languages. |
data-position | position | right or left. Overrides the dashboard setting on this page. |
data-open | open | true opens the panel when the page loads. A visitor who closed it isn't overruled. |
When both are present, the attribute on the script tag wins.
Things to know
- Commands run in the visitor's browser. Nothing here needs an API key, and nothing here can read other visitors' data.
- Single-page apps don't need extra calls when the route changes. See Single-page apps.
- Content Security Policy applies to the widget like to any script. See Content Security Policy.
- Server-to-server access to your workspace uses API keys, not this API. See API keys.