Lexer Chatbot API Developer Info

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”