Behind the scenes: Your widget, your way with the JavaScript API

The JavaScript API lets you create unlimited automations and customizations for your widget. In this conversation with Mārtiņš, Lead Backend Engineer at, discover some of the most popular use cases for the JS API and learn how to avoid the most common mistakes. You’ll also get a preview of what’s coming next for the API at and the opportunity to get access now.

1 — What is an API and what can it do?

API stands for Application Programmable Interface. It's a means for two different software applications to talk to each other. In this case, for JavaScript API in particular, it would be used on the website the widget is currently on to influence and control the widget's behavior and different aspects of it.

2 — What are some of the benefits of using the JavaScript API? 

With the JavaScript API, there are things you can do that otherwise may be difficult to do when you answer a chat in the dashboard or respond to events on your website. For example, you can maximize the widget from your website's JavaScript — or minimize it if need be.

One common use case is to have a "Contact us" button with the widget fully hidden until the button is clicked. To do this, you would set the widget to be hidden on initial load. Then, you would simply maximize the widget and make it visible when the "Contact us" button is clicked.

You can also react to the widget in different ways. We can set up events, for example, when the widget is loaded, or when the widget is maximized or minimized. You could tweak your website content depending on the widget state. Really, the imagination is your limit to what you could do.

3 — Can we replace the default user ID with the visitor’s name and email? 

That is definitely one of the common use cases. There are a couple of ways that can be done.

So let's say you have a CRM and you have this data already available. What you can do is add properties for name and email to a visitor object. As the widget is starting up, it will automatically pick this information up and send it to And you can immediately see your visitor’s name and email.

If the widget is already operational, as in it has already loaded, what you can do, and this brings us to another cool feature, is you can set the visitor name and email as attributes. And you're not only limited to name and email. You could set many an attribute. Let's say you want to set what plan your customer is currently on. That could be a custom attribute. These custom attributes will be displayed in your chat sidebar in the Details tab.

4 — Can we add a phone number with the JavaScript API?

You would set an attribute titled “phone.” Currently, we do not have explicit phone support. As such, you can set it as a text attribute. We have an exciting new thing coming up — our new CRM — where you will be able to set phone. You will be able to set multiple emails and phone numbers, and there are many more cool features. I don't want to show our cards too much yet, but it's very near and we're very excited about it, which is going to make the attributes feature even more useful and powerful.

5 — What are common mistakes people make when using the JavaScript API?

One of the most common mistakes we see is that people try and get the API to do things before the API is even ready to accept commands and send events.

As such, we have an event that is called onLoad. The common mistake is that people try to immediately send commands telling the widget to minimize or maximize and then wonder why they don't work when the widget itself and the underlying API have not yet loaded.

The second mistake that I see most often is enabling the secure mode without actually understanding what the secure mode does and the prerequisites necessary for the secure mode to work.

6 — Is a REST API available at 

We do have a private beta Rest API that is currently available to our partners. If you are a partner and you’re interested in REST API access, just reach out to your nearest representative.

The Rest API is geared more towards performing actions on behalf of an agent. If the JavaScript API is purely intended to control the widget on your website, then the Rest API is geared towards performing actions as an agent. We have a lot of useful things there now. We keep expanding it. But right now, the common use cases that we see are creating properties for your customers, inviting them automatically, and reading conversation history.

You can also do things like manage webhooks and your knowledge base through REST API. So let's say you create the property for your customer and you want some basic Knowledge Base entries created from the get-go. That's something that you can automate with the REST API.

And if you have a really cool use case, let us know, and we'll see if our Rest API is a fit for you.

View our JavaScript API Documentation in the Developer Platform.

Request access to the REST API here: Get beta access to the REST API

Was this article helpful?

128 out of 165 liked this article

Still need help? Message Us