ChipBot API

Overview

This page will contain all the necessary instructions to integrate ChipBot. If you want to integrate ChipBot without coding, please read the No Code Integration section, which introduces Zapier as a great medium between us and your services.

No Code Integration

ChipBot has direct interaction with Zapier. Zapier is a platform that enables your other services to connect to ChipBot. For example, you may want to populate your CRM with ChipBot’s email and name data. You can create a new ChipBot Zap to connect to your Salesforce Zap, then populate your CRM funnel by connecting the fields.

If you want to connect to ChipBot’s Zap, please email support@getchipbot.com so we can invite your account.

This is an ideal solution if you want to get up and running fast without programmatically creating your own API integration. If you want to tap into the raw sources without going through Zapier, continue reading on.

Error Handling

In rare occasions, you may encounter an unresponsive HTTP response from our API. For the majority of the cases, these are maintenance updates. These windows usually only last for about 20 seconds or less and happen as frequent as once per day. We do not have a status page yet but we plan on adding one once usage or severity calls for it.

You’ll need to account for the following error workflows:

• 502 Gateway Error – Usually a maintenance or service disruption issue. Retry every 60 seconds.
• 401 Unauthorized Error – Your API key or session token has expired or has been invalidated by the end user (through key rotation)

If you want to monitor our API service to availability, you can optionally call our public health check endpoint.

curl https://getchipbot.com/healthcheck

Code Samples

All server-side code samples are in bash using curl. The API is all over HTTP so you can write the API integrations in any language or use any REST client for testing.

curl https://getchipbot.com

All client-side code samples are in JavaScript.

chipBotApi.open();

Authentication

Note: If you’re looking to manipulate the ChipBot client, skip down to Client API. You do not need to server-to-server authentication for browser-side API access.

ChipBot has a simple 2 legged process to have server-to-server integrations. Will use an API key to authenticate against ChipBot’s Server APIs by calling the connect endpoint. You need to execute this step in order to return a session token.

A session token is a short-lived access token that allows you to access allowed API resources. Every time you want to interact with ChipBot’s Server APIs, you’ll need to ensure your token is not expired. A 401 error code will return if your session token expires.

To start the authentication process with a valid key, go to the Integrations page on your dashboard.

Server API

Server API endpoints are used to listen to events or ingest raw data from ChipBot. All resource-based endpoints require an authentication step.

Connect

Authenticate and establish a new user session using an API token.

For normal accounts, go to Settings, and then Integrations to get your API key.

For white-label SaaS accounts, go to your Admin Dashboard, go to Settings, and get the API key.

HTTP Request Spec

[POST] /api/v1/connect

HTTP Request Example

curl -X "POST" "https://getchipbot.com/api/v1/connect" \
     -H 'X-Api-Key: R9iAzY...'

HTTP Response Example

{
  "status": "OK",
  "data": {
    "token": "eyJhbGciOiJ...",
    "id": "sIOR...",
    "accountId": "Ph49...",
    "domainId": "Dhu...",
    "domainName": "getchipbot.com",
    "expiresIn": "2038-01-28T03:14:08Z",
    "type": "domain",
    "apiKey": "R9iAzY6"
  },
  "timestamp": "2038-01-28T03:14:08Z"
}

Use data.token as the session token for all resource-specific API requests. This token will always be the Authorization value in HTTP requests.

White Label SSO

HTTP Request Spec

[POST] /api/v2/connect/accounts/YOUR_ACCOUNT_ID/auth/email

HTTP Request Example

curl -X "POST" "/api/v2/connect/accounts/YOUR_ACCOUNT_ID/auth/email" \
     -H 'Authorization: exc123...'
     -d $'{"email": "TARGET_SSO_EMAIL"}'

HTTP Response Example

{
  "status": "OK",
  "data": {
    "oneTimeUserToken": "eyJhbGciOiJ...",
  },
  "timestamp": "2038-01-28T03:14:08Z"
}

Poll Emails

Returns a list of recent unique contact information. Use the id field to handle deduplication.

HTTP Request Spec

[GET] /api/v1/connect/accounts/{accountId}/domains/{domainId}/emails/poll

HTTP Response Example

{
  "status": "OK",
  "data": [
    {
      "id": "jdoe@outlook.com",
      "email": "jdoe@outlook.com",
      "name": "John Doe"
    }
  ],
  "timestamp": "2038-01-28T03:14:08Z"
}

Poll Questions

Returns a list of recent questions submitted to Chipbot. Use the id field to handle deduplication.

This resource returns both questions and feedback inqueries.

HTTP Request Spec

[GET] /api/v1/connect/accounts/{accountId}/domains/{domainId}/feedback/poll

HTTP Response Example

{
  "status": "OK",
  "data": [
    {
      "type": "question",
      "opened": false,
      "name": "John",
      "email": "jdoe@gmail.com",
      "contents": "What is your refund policy?",
      "searchQuery": "refunds",
      "accountId": "Ph49...",
      "domainId": "Dhu...",
      "id": "KLa...",
      "createdAt": "2038-01-28T03:14:08Z",
      "notifiedDate": "2038-01-28T03:14:08Z"
    },
    {
      "type": "feedback",
      "opened": true,
      "name": "John",
      "email": "jdoe@gmail.com",
      "contents": "The site is great",
      "accountId": "Ph49...",
      "domainId": "Dhu...",
      "id": "aMH...",
      "createdAt": "2038-01-28T03:14:08Z",
      "notifiedDate": "2038-01-28T03:14:08Z"
    },
  ],
  "timestamp": "2038-01-28T03:14:08Z"
}

[GET] /api/v1/connect/accounts/{accountId}/domains/{domainId}/insights

{
  "status": "OK",
  "data": [
    {
      "title": "Test Content",
      "contents": "<p>Test Content</p>",
      "id": "ins_MS0CL0hT1JcY",
      "draft": false,
      "createdAt": "2020-03-05T18:24:44.562Z",
      "updatedAt": "2020-03-16T00:31:23.631Z",
      "analytics": {
        "views": 1,
        "impressions": 0,
        "ratingCounter": 0,
        "rating": 0,
        "ratingPositive": 0,
        "ratingNegative": 0
      }
    }
  ],
  "timestamp": "2038-01-28T03:14:08Z"
}

Client API

Unlike server endpoints, client endpoints do not need authentication. These are APIs available within the JavaScript browser context when ChipBot is loaded on the page.

General Usage

On ChipBot Ready

If you want to call ChipBot API before ChipBot is fully loaded, you’ll need to use ChipBot’s onReady handler to execute ChipBot code after the library is loaded in.

window.asyncChipBotApi = window.asyncChipBotApi || [];
window.asyncChipBotApi.push(['onReady', () => {
 // execute code when ChipBot is loaded
}]);

Open Nexus

chipBotApi.open();

Note: Calling open(); will always temporarily suspend any visibility rules configured on ChipBot. This makes it convenient to have ChipBot hidden by default but triggered manually through custom open calls. Anytime the user closes ChipBot or if close(); is called, visibility rules will be re-enabled.

Open Nexus (HTML)

<a class="chipbot-open-knowledge-base">Open FAQs</a>

Close

chipBotApi.close();

Hide ChipBot Visibility

chipBotApi.hide();

Show ChipBot Visibility

chipBotApi.show();

Render ChipBot Button

chipBotApi.renderBaseIcon(document.querySelector('div'));

You can also render by setting class=”chipbot-render-base-icon” on a specific element on the page.

Show Video

chipBotApi.showVideoIcon('Pylon ID');

Hide Video

chipBotApi.hideVideoIcon();

Open Video

chipBotApi.showVideoExperience('Pylon ID');

Open Knowledge Base Article

chipBotApi.kbOpenArticle('Article ID');

You can obtain the Article ID when previewing an Article within the Knowledge Base.

Open Knowledge Base Article in a Modal

chipBotApi.kbOpenArticleModal('Article ID');

Product Information

chipBotApi.getProductInfo();

Session Information

chipBotApi.getSessionInfo();

Open Category

chipBotApi.kbOpenCategory('Category Node ID');

Open Calendly Booking

chipBotApi.openBookingForm();

List all registered videos

chipBotApi.getVideoExperienceList();

Open Live Chat

chipBotApi.openLiveChat();

Open Live Chat (HTML)

<a class="chipbot-open-chat">Open Live Chat</a>

Listen to User Behavior Events

chipBotApi.eventManager.on('reporting.all', e => console.log(e));

Open Contact Form

chipBotApi.openContactForm('prepopulated.email@gmail.com', 'Name', 'Prefilled Content');

Get Articles

chipBotApi.getArticles();

Render video grid

chipBotApi.renderVideoGrid(document.querySelector('.my-class-name'));

Render video icon

chipBotApi.renderVideoIcon(document.querySelector('.my-class-name'), {videoExpId: 'videoexp_ID'});

Render video grid (HTML)

<div class="chipbot-render-video-grid"></div>

Render embed video

chipBotApi.renderEmbedVideo(document.querySelector('.my-class-name'), {videoExpId: 'videoexp_ID'});

Render embed video (HTML)

<div class="chipbot-render-embed-video" data-video-exp-id=""></div>

External Components

External components are extra features from the ChipBot platform that adds enhancements to your website by using HTML or JavaScript.

Video Grid Component

Shows a grid of all your videos that are stored within ChipBot.

<div class="chipbot-render-video-grid"></div>

Config

Note: This is an experimental API. If you have use cases where you may want to dynamically configure ChipBot, please reach out to support@getchipbot.com or ask a question in ChipBot on the bottom right.

chipBotApi.setConfig('theme', 'dark');

chipBotApi.eventManager.on('reporting.all', e => console.log(e));