The Gist JavaScript API


By Jitta Rao

updated 2 months ago

The Gist JavaScript library provides a Gist JavaScript object that responds to a few methods that allow you to update users without a page refresh and interact with the message window. Here is a guide to using the JavaScript API.

Identifying Leads and Users with Gist JavaScript API

Here are the different types of Gist JavaScript API that you can use to connect to other apps.

1. Track Logged-In Users And Their Properties

When you want to track logged in uses; for instance, membership site or your SaaS app, and you want to send those users and their data to Gist, use the following code.

gist.identify("12345", {
    "email": "",
    "name": "John Doe",
    "user_id": "12345"
    "subdomain": "app",
    "last_paid_at" : 1283495946,

Please note that for this code to work, user id and email are mandatory attributes. You can also add any number of optional attributes to pass on to Gist.

This is the only method you can use to identify logged in users/customers on Gist.

If you want to identify leads or subscribers who are not registered for membership on your site or app, then you can use the following:

2. Track Leads Without Custom Properties

If you're sending only the email address and do not want to collect other properties, then the syntax is:


3. Track Leads With Custom Properties - Version 1

If you wish to send other custom attributes along with the email address, then the syntax is:

    email: "email_address",
    name: "name",
    restaurant_type: "fine_dining"

4. Track Leads With Custom Properties - Version 2

This is another variation of the syntax above. If you are already using JavaScript code for identifying logged in users, as mentioned in 1., then you can use the same syntax, along with an empty string for user ID.

gist.identify("", {
    email: "email_address",
    name: "name",
    restaurant_type: "fine_dining"

Tracking Custom Events

You can send an event using the gist.track() method. This will associate the event with the currently logged in user and send it to Gist. The final parameter is a map that can be used to send optional metadata about the event.

Here's a separate detailed guide to learn how you can send custom events to your Gist workspace.

Gist JavaScript API for Chat Messenger

Following is the JavaScript API you can call to show, hide, or load the Gist chat messenger on specific pages and to specific users.

Check If Gist Javascript API Is Ready

The ready event indicates that Gist Messenger widget is loaded and the API is ready for use.

document.addEventListener('gistChatReady', function () {
    // your code goes here

It is highly recommended that you wrap any usage of the method around the ready event listener.

Hide the Chat Messenger

This call will hide the Gist chat messenger if it is loaded on that particular page. It will not hide the Messenger Launcher everywhere in general, but just hides on those pages where this script loads. To make this happen, you can call the following API method.'hide');

This is useful if you want to hide the chat messenger by default on a page and only display it when an event is triggered by your users, such as clicking a link or a button.

Show the Chat Messenger

This will display the Gist chat messenger on the page on which this API is called. To make this happen, you can call the following API.'show')

You can use this API call to show the chat messenger only on specific pages of your website, such as your 'app' or member login area.

Launch Gist Messenger on Clicking a Link

You can launch the Gist Messenger without the Gist launcher using the following API method:'openConversationList');

For example, you can add a link anywhere on your site, including HTML text or buttons on a particular page and turn it into your own custom Gist Messenger launcher.

If you are using jQuery library, here are code sample that demonstrates how you can apply this method:

document.addEventListener('gistChatReady', function () {'openConversationList');

Note: Call the above-mentioned method only after the chat window gets loaded to your page. If not the conversation list will not be displayed.

Open a New Conversation on Clicking a Link

You can set up Gist to launch the chat messenger when your users perform a specific event on your website, such as clicking a link or a 'Contact Us' button. To make this happen, you can call the following API.'openNewConversation');

This function can also take an optional second parameter, used to pre-populate the message composer as shown in the code example below.'openNewConversation', 'pre-populated content');

For example, you can add a link anywhere on your site, including HTML text or buttons on a particular page, which when clicked will load the Gist chat messenger ready for a new conversation. This can be used to enable chat to only those users that perform those actions and avoid everyone else.

If you have any questions about our pricing, please <a href="#" onclick="'openNewConversation', 'Question about pricing: ')">contact our support team</a>

Example use case:

If you do not wish to display the chat messenger by default, but only launch it when a user clicks on a link or button on that page, you can use a combination of the'hide'); and'openNewConversation'); calls to achieve this.

Open a Help Article within Messenger

There are many ways to open a Help Article within Messenger via any element on your site, and you can choose to do it using a custom HTML data attribute, or with the Gist JavaScript API.

All you’ll need is the Article’s ID, which can be found in the URL of the article you want to open. The editor URL is structured like this:[ARTICLE ID]-article-slug

Using Custom HTML

Data attributes are the simplest way to open a Help Article via any link or button on your site. There are two different attributes you can choose from, which can be used to open the article in Messenger, or in a sidebar. Check out the examples and demos below for more information on how to use them.


<!-- Open Article in Messenger-->
<a href="javascript:void(0)" data-gist-article="ARTICLE_ID"></a>

<!-- Open Article in a sidebar -->
<a href="javascript:void(0)" data-gist-article-sidebar="ARTICLE_ID"></a>

Using JS API

Alternatively, you can use the'article') method to open the Article within Messenger, or in a sidebar. This is helpful when your trigger is something other than a link or a button, or when you’d like the article to show up automatically using your own custom logic.

Note: If the Messenger is closed when this method is called, it will also open the Messenger automatically.


// Open Article in Messenger'article', 'ARTICLE_ID')

// Open Article in a sidebar'article', 'ARTICLE_ID', 'sidebar')

If you are not familiar with Javascript code, don't fret. Here's a quick HTML code that you can copy into your page to open any article you need.

<a href="javascript:void(0)" onclick="'article', 'ARTICLE_ID')"></a>

Replace ARTICLE_ID with the ID of the article from the URL structure.

Need Help?

If you have any questions, please start a Live Chat. Just "Click" on the Chat Icon in the lower right corner to talk with our support team.

Did this answer your question?