We offer a RESTful API that allows you to build a conversational experience inside your own app, platform, or third-party tool of your choice. Here, we’ll explore how to generate the token required by the endpoint, as well as the endpoint itself.
How to generate your API token
Once your bot has been created on the Certainly Platform, you'll need to generate an API token. This API token is the Bearer token belonging to the bot. It needs to be passed in our Get Bot Response API as an Authorization header.
The API token is generated within the platform. Open Bot Settings from the right sidebar menu, then navigate to Channels > Certainly Widget. Under the "Chat API" section, select "Generate API Token". The token will appear in the field below the button. Select "Copy Token" to copy for use.
Should you need to revoke this token and generate a new one at any point, simply select "Generate API Token" again.
Send End User Message (POST)
The REST API uses the following path:
https://app.certainly.io/webbot/api/webchat/bot/<bot-deployment-id>/messages/
To find your bot's deployment ID, navigate to Channels > Certainly Widget and locate "id" in the widget script.
Below, we'll share information on the following:
Headers
| Header | Description | Example |
|
Authorization |
This endpoint requires the use of basic authentication. Replace [[bearer_token]] with the token generated using the instructions above. |
Authorization: bearer [[bearer_token]] |
|
Content_Type |
The endpoint response is in JSON format, so it is necessary to indicate that the Content-Type is application/json. | Content-Type: application/json |
Example Request Body
{
"from": "human",
"user_profile": { // Optional
"surname": "doe"
},
"ref": "123456", // Required, can be an empty string
"user_cvars": {
"a": "b"
},
"user_id": "myRestAPIUserId3",
"timestamp": 1654251574, // Optional
"attachments": [], // Optional
"id": "1653753771388", // Optional
"actions": [{
"type": "standby",
"text": "hello from standby user"
}]
}
Request Parameters
- from: Belongs to the entity sending the message. As it represents the end user, it will be "human".
- user_profile: Optional. Profile of the end user. Any user-related information can be passed. It will be stored as metadata belonging to that user and can be used as Custom Variables in the platform. It has to be a valid JSON.
- ref: Required. Any valid Module ID belonging to the bot can be passed here and the conversation will move to that Module (i.e. "ref": "123456").
- user_cvars: Similar to user_profile, can be used to pass user-related information and can be used as Custom Variables in the platform. It has to be a valid JSON.
- user_id: User identifier. Any valid string from length 0 to 255 can be passed here.
- timestamp: Optional. Should be the 10-digit current timestamp. Conversation expiration and new conversation creation are based on this timestamp.
- attachments: Optional. List of attachments. The handling of attachments is not supported yet, so this field can either not be included in the payload or be passed as an empty array [].
- id: Optional. This is the message identifier. Any valid ID can be passed.
- actions->type: Type of the message. It can be either "text" or "standby".
- text: Represents the end user message for the bot. The bot will produce the response.
- standby: Represents the handover case. This means the bot has handed over the conversation to a human agent. As such, all agent and end user messages can be sent to this API using type as "standby". In this case, the Certainly Platform will record the messages but not produce any response. These messages will be visible in reports.
- actions->text: Text the end user and/or agent has entered into the external system. This will be treated as a user message, and Modules will be evaluated against this.
Example Response Body
[
{
"error": null,
"message": [
{
"bot_module": {
"id": 72,
"name": "New Module",
"group_colour": null,
"kpi_tags": []
},
"connections": {
"id_message_evaluate": "1653753771388",
"reply_to_module_id": 68,
"data": [
{
"type": "local",
"fallback": true
}
]
},
"from": "bot",
"actions": [
{
"type": "text",
"text": "bot example message"
}
],
"id": 1695,
"conversation_id": 277
}
]
}
]
Response Parameters
- bot_module: Module where the user has landed. All details like ID, name, color, and KPI tags are present in this JSON.
- connections: Represents the evaluated connections, as a result of which the bot produced the given response.
- actions: Represents the bot response. There are 2 parameters, "type" and "text".
- type: Can be text, audio, video, image, choice, wait, and so on.
- text: Message added in the Module the end user has landed on, and which the bot has produced as the response.
- id: ID belonging to the message stored in Certainly's Platform and produced as a response of this API.
- conversation_id: ID of the conversation created between the bot and the end user. It can be used in the Inbox and reports to fetch the conversation details.
Additional considerations
Trigger APIs
The Trigger APIs like Trigger Message and Trigger Response cannot work for REST APIs. However, the Trigger Response API can still be used to store user_cvars if required.
Handover
For handover, when the bot needs to shut down, simply don't call this API. Upon takeover, this API can be called once again and the bot will respond.
As noted above, the "standby" action type can be used to record messages exchanged between an agent and the end user so they are later available in the Inbox and used for re-training the AI model of the bot.