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 install the SDK using NPM
https://npm.io/package/@botsquad/inbox-sdk
Or by using the hosted version at
https://inbox.dialox.ai/assets/sdk.js
which will expose a window.InboxSDK
object.
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"
}
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.
// npm:
import { InboxSDK } from '@botsquad/inbox-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 conversationswatched
: 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)
})
}
})