Skip to content

Inbox

Introduction

The Inbox SDK is a Javascript library that communicates over an authenticated socket to provide access to the Inbox. The primary purpose is to embed the Inbox chat window in an iframe on your own webpage.

Installation

You can start using the Inbox SDK by adding the following script tag to your page:

<script src="https://inbox.dialox.ai/assets/sdk.js"></script>

This will expose a window.InboxSDK object.

Reference

See full reference

Usage

In order to interact with the Inbox SDK, you will have to authenticate first. For this you'll need a JSON Web Token (JWT). This token identifies the agent that's interacting with the inbox.

The body of the token has the following fields, plus a scope (see below).

{
 "iss": "Your application name",
 "exp": 1711634350,
 "iat" => 1711634150,
 "name" => "Full name",
 "email" => "operator@example.com",
 "id" => "my-application/a32346d1-3d6b-4552-b6f2-aad710855f00",
 // Optional:
 "roles" => ["agent", "operator", "supervisor"]
}

The id field can be anything that can help identify this user in your own system. This field is then exposed as the externalId field in various places, such as the StudioUser object.

The scope of the token can be either:

  • Bot-scoped by setting a bot_id with the UUID of the bot. The JWT must then be signed with the API key of the bot.
  • Environment-scoped by setting an environment_id. The JWT must be signed with the API key of the environment.

Once you have a JWT, signed with the correct API key based on scope, you can start to interact with the SDK.

// or, when using the hosted version:
const InboxSDK = window.InboxSDK;

const jwt = "my jwt token";

const options = {
  iframeParent: document.getElementById("conversation-container"),
  languageCode: "en",
};

InboxSDK.authenticate(token, options).then((inbox) => {
  // Interact with the authenticated inbox.
  // All the examples below assume we're working from this block.
});

Example: Listing my conversations

The SDK exposes various "inboxes":

  • mine: The conversations that are assigned to me.
  • new: Escalated, but not yet assigned conversations
  • watched: Conversations that you're currently "watching".

These correspond to the same tabs in the Inbox UI.

inbox.mine({
  // This function is called anytime the list of my conversations is updated.
  // More fine-grained functions (such as onRemove, onNew) are also available.
  onSync(conversations) {
    // We can also just open the first one in the iframe:
    if (conversations[0]) {
      inbox.navigateToConversation(conversations[0]);
    }
  },
});

Example: Starting a new conversation

Some channels, such as Whatsapp or email, allow the agent to start a conversation. For example, assuming that there is a Whatsapp channel configured on the bot(s), we can start a new conversation and then immediately open the new conversation in the iframe:

inbox.listInitiateableChannels().then((channels) => {
  const whatsapp = channels.find((c) => c.type === "whatsapp");
  if (whatsapp) {
    inbox.startConversation(whatsapp, "0612345678").then((conversation) => {
      inbox.navigateToConversation(conversation);
    });
  }
});