This document provides all the basic information you need to start using the Hyperchat API. It covers important concepts and shows examples for various use cases.

For advanced configuration information, see the API Routes and API Definitions sections.

Authorization

All requests to Inbenta APIs endpoints must be authenticated and authorized:

• Authentication is the method that the APIs use to identify you.
• Authorization gives you the access token that manages your session.

Every chat integration needs a registered app to be identified and authenticated on the server. All the data that generates your integration is associated with your app ID, which is generated by the server whenever the app is registered.

When an app is registered, it generates two keys and the App ID:

• The App ID identifies your app.
• The Secret grants access to your instance’s data.
• The Domain Key allows requests to access your instance's data, but only when those requests are coming from the browser (front-end integrations) and from a limited set of domains.

Contact your Inbenta representative to request your credentials if you did not receive them during the instance setup process.

Note

For a complete description of keys and authorization methods, see the Authorization section.

The Domain Key gives you access to only the following endpoints: GET /agents/available, GET /agents/online, POST /agents/login, GET /apps/{appId}/validate, GET /settings and POST /users.

When a call is made to the GET /settings endpoint using a Domain Key, the response returned is a subset of the data, meaning the endpoint returns only queue and language data.

Caution

Specifying the region and version

The Hyperchat service URL looks like this:

https://hyperchat-{region}.inbenta.chat:8000/{version}

You must define the region and version variables. 

• region: Inbenta will provide you this one, which is basically the cloud region where your Inbenta chat app is registered.
• version: the API version you will be using. Valid values are: v1

Examples:

The current valid endpoint for an app registered in Europe would look like this: https://hyperchat-eu.inbenta.chat:8000/v1
The current valid endpoint for an app registered in the United States would look like this: https://hyperchat-us.inbenta.chat:8000/v1

Using the API

Authentication

In order to authenticate all your requests to the HyperChat API, you have to provide your app ID and in every request in the following headers:

x-hyper-appId
x-hyper-secret

This headers identify your app in the server and let you perform all the actions you need to build your application.

Start a Chat

To create a chat, follow these steps:

1. Check if there are agents available in the chat room
2. Signup a user (or get an existing one)
3. Create the chat
4. Look for an agent to get the chat

Check For Available Agents in a Room

Before you create a chat, you must check if there are any agents available in the room where you want to create it. Otherwise, you will create a chat that will get lost because no one was able to attend it.

The following request checks if there are available agents for a roomId in your app:

GET /v1/agents/available?roomIds=<roomId> HTTP/1.1
Host: hyperchat-eu.inbenta.chat:8000
x-hyper-appId: <your-appId>

Use the response to this request to know if it is possible to open a chat and there is someone available to attend it.

Signup a User (or Get an Existing One)

To create a user, the only required property is the name.

You can also add an externalId to reference the user later on, especially if you cannot keep state between requests, and are integrating with an external service.

A sample request to register a new user is:

POST /v1/users HTTP/1.1
Host: hyperchat-eu.inbenta.chat:8000
x-hyper-appId: <your-appId>
Content-Type: application/json
 
{
 "name": "username"
}

Keep the user ID that this request returns as you need it later to create the chat on their behalf.

Create a Chat

A chat must be created by a user and assigned to a room. Here, we use the user we just created in the previous section:

POST /v1/chats HTTP/1.1
Host: hyperchat-eu.inbenta.chat:8000
x-hyper-appId: <your-appId>
x-hyper-secret: <your-secret>
Content-Type: application/json
 
{
    "room": "<roomId>",
    "creator": "<userId>"
}

Keep the chat ID that is returned by this request, you'll need it later to make any kind of actions which involve this chat (like sending messages or closing it).

Assign the Chat

Once the chat is created, we have to trigger an agent search so that the conversation can start. This will use an algorithm configured to fetch an agent among the ones that are available in the chat room, and send them an invitation to chat. The default algorithm looks for the agent who has the most free "capacity slots".

A sample request is:

GET /v1/chats/<chatId>/assign HTTP/1.1
Host: hyperchat-eu.inbenta.chat:8000
x-hyper-appId: <your-appId>
x-hyper-secret: <your-secret>

Start a Chat (using queue mode)

In order to successfully create a chat, you must follow the following steps:

1. Check if there are agents online in the chat room
2. Signup a user (or get an existing one)
3. Create the chat
4. React to queues:update or users:join event

Check For Online Agents in a Room

Before you create a chat, you must check if there are any agents online in the room where you want to create it.

The following request checks if there are online agents for a roomId in your app:

 GET /v1/agents/online?roomId=<roomId> HTTP/1.1
 Host: hyperchat-eu.inbenta.chat:8000
 x-hyper-appId: <your-appId>
 

You can use the response to this request to know if a chat can be opened and if someone is available to attend it.

Signup a User (or Get an Existing One)

Same steps as Signup a User (or Get an Existing One) without using queue mode described above.

Create the Chat

Same steps as Create a Chat without using queue mode described above.

After a successful response, the chat is added to the queue of the specified room.

React to queues:update or users:join event

After the chat is created, if you have a webhook set up for the queues:update, you can track the position in the queue and the estimated waiting time to be attended. If you have a webhook for the users:join event, you can track when an agent joins the conversation and therefore the conversation can be started.

Send a Message

To send a message to an open chat, just use the provided the chat and user IDs.

A sample request is:

POST /v1/chats/<chatId>/messages HTTP/1.1
Host: hyperchat-eu.inbenta.chat:8000
x-hyper-appId: <your-appId>
x-hyper-secret: <your-secret>
Content-Type: application/json
 
{ 
    "chatId": "<chatId>", 
    "sender": "<userId>",
    "message": "<your-text-message>"
}

Close a Chat

To close a chat, use the provided chat ID. Only providing the chat ID will close the chat as if the "system" does it. If you want to close the chat on user's behalf, simply provide it's ID too.

A sample request that closes a chat on behalf of the user is:

DELETE /v1/chats/<chatIdd> HTTP/1.1
Host: hyperchat-us.inbenta.chat:8000
x-hyper-appId: <<your-appIdd>
x-hyper-secret: <your-secretd>
Content-Type: application/json
 
{
    "userId": "<userId>"
}