Chatbot User API

Allow your chatbot to claim and close messages

Our integration with chatbots is designed around the principle that your chatbot is another member of your team. We create a ‘bot user’ account and it has its own password (API token).

When the chatbot responds to your customer, it tells Lexer via our API and we mark the response as being written by the bot. When the chatbot is handling the conversation, it is taking ownership and closing the messages from within Engage, just like other members of your team. Your team can see when your chatbot has handled a conversation in the conversation context, making it easy to catch up if your customer asks to speak with a human.

Our handover process is simple. If your chatbot understands that it can no longer manage the conversation, it just stops claiming the conversation via the API. This will result in all subsequent messages appearing in your inbox, alongside all of your other messages, posts and comments.

Authentication

First you add a new Bot User to your team, which can be done within Settings. Once created, your bot user will have it’s own access token and examples of the actions we’ve described below. All requests to the Chatbot API are authenticated with an API token that must be sent via the Auth-Api-Token HTTP header.

Action 1: Claim ownership and close

Description

Our first API endpoint is to be used for all messages your chatbot receives while handling the conversation with your customer. The claim and close action is removing the messages from the Engage workflow.

The handover process is done by simply ceasing these API requests. All subsequent messages will then enter the Inbox queue and a Customer Service Agent will pick it up.

Example

curl -H "Content-Type: application/json" -H "Auth-Api-Token: <ACCESS_TOKEN>" -X POST https://clients.lexer.io/api/clients/<CLIENT_ID>/bots/objects/claim -d '

{
"object_id":"<OBJECT_ID>",
"published_at":"<CREATED_TIME>",
"source": "facebook",
"state": "closed",
"account_id": "<FACEBOOK_PAGE_ID>"
}'

Action 2: Mark response as created by bot

Description

Our second API endpoint is to be used for all messages that the chatbot sends to a customer. It is indicating that this particular response has been generated by the chatbot and will inform the Customer Service Agent that it was an automated response.

Example

curl -H "Content-Type: application/json" -H "Auth-Api-Token: <ACCESS_TOKEN>" -X POST https://clients.lexer.io/api/clients/<CLIENT_ID>/bots/objects/echo -d '

{
"object_id":"<OBJECT_ID>",
"published_at":"<CREATED_TIME>",
"source": "facebook",
"account_id": "<FACEBOOK_PAGE_ID>"
}'

API request example

Let’s deconstruct a webhook message received from Facebook to understand which fields are required to interact with the Chatbot API.

{
"Sender":{
"id":"USER_ID"
},
"Recipient":{
"id":"PAGE_ID"
},
"Timestamp":1458692752478,
"Message":{
"Mid":"mid.1457764197618:41d102a3e1ae206a38",
"text":"hello, world!",
"quick_reply": {
"payload": "DEVELOPER_DEFINED_PAYLOAD"
}
}
}

The parameters expected by the Lexer API could be retrieved from the message as per the table below:

Lexer API Parameter

Messenger API

Type

Comments

object_id

message.mid

String

ID for the message being actioned

published_at

timestamp

String or Integer

Can be an epoch eg. 1458692752478 or an ISO8601 date eg. “2017-08-01t05:29:44Z”

source

facebook

String

Always “facebook”

state

closed

String

Always “closed”

account_id

recipient.id

String

Facebook page ID

client_id

n/a

Integer

ID of the Lexer client, found with the access token associated with the Bot User in Lexer Hub. Must be used in the URL

Responses and errors

List of error codes, the body returned and their description.

Status

Body

Description

201

{“status”:”ok”}

Request was successfully accepted by Lexer

400

{“status”:”400 Invalid Account”,”error”:”Cannot find an integrated account: 12345”}

Integrated Facebook page cannot be found within Lexer

500

Scary HTML response

Invalid JSON or invalid parameter

500

{“error”:”object_id is missing”}

Required field is missing

500

{“error:”source does not have a valid value”}

Source value is not “facebook”

500

{“error”:”state does not have a valid value”}

State value s not set to “closed”

Powered by HelpDocs (opens in a new tab)