API Setup

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:

  • The App ID identifies your app.
  • The Secret grants access to your instance‚Äôs data.

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

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations.

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.

Caution: Your Secret must remain confidential. To prevent third parties from accessing your API, always perform this request in a server-side environment. Never expose your secret in client-side integrations.

Start a Chat

In order to create a chat, you must follow the following 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>

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