GetChipBot.com

API Documentation

Welcome to ChipBot API docs page. Below is an overview of how to securely authenticate ChipBot and how to interact with ChipBot's available REST endpoints. Use our API to securely consume end-user questions, events, and reports to your services.

ChipBot API Docs

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.

Zapier

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, refer to the connect endpoint below.

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.

You will need to obtain the user’s API key to access this endpoint.

API token retrieval example

HTTP Request Spec

[POST] /api/v1/connect
HTTP Headers
X-Api-Key User’s API Key

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.

apiKey is only the first 7 characters of the original API key. Use this to help debug authentication issues.

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 Headers
Authorization Session token.
URL Parameters
accountId Account ID specified from the session response.
domainId Domain ID specified from the session response.

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 Headers
Authorization Session token.
URL Parameters
accountId Account ID specified from the session response.
domainId Domain ID specified from the session response.

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"
}

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

Open

chipBotApi.open();

Close

chipBotApi.close();

Hide

chipBotApi.hide();

Show

chipBotApi.show();

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
}]);

Forms

Ask Form

Note: First argument is optional.

chipBotApi.openAskQuestionForm('prepopulated.email@gmail.com');

Feedback Form

Note: First argument is optional.

chipBotApi.openFeedbackForm('prepopulated.email@gmail.com');

Events

If you want to track conversions or measure ChipBot’s performance against existing tracking data, you can emit custom events and track them in ChipBot’s reporting dashboard.

The second argument in each example can be customized.

The third argument must always be an object and contain a property value.

Example 1

chipBotApi.pixel('event', 'AddToCart');

Example 2

chipBotApi.pixel('event', 'AddToCart', {value: 9.99});

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');

Follow Us On Social Media

-

ChipBot Interactions

Learn ChipBot
ChipBot, Inc.2019 ChipBot, Inc. All Rights Reserved.