Chatbox user API

Allow your chatbot to claim and close messages

Lexer's Chatbot User API enables your chatbot to close messages from your Respond Inbox while it has control of a conversation on Facebook or Twitter. It's designed around the principle that your chatbot is another member of your team with limited permission to claim messages, close messages, and echo responses that it has published.

How it works

As your chatbot is handling the conversation with a customer, it constantly hits the Lexer API to 1) Claim ownership and close messages from the inbox, and 2) Echo responses it has published. Claiming ownership and closing messages will remove them from the inbox so your team are not double handling messages. Echoing responses will update the conversation history to show your team members that particular replies have been sent from the chatbot, and not members of your team.

If your chatbot is unable to resolve the customer's query, and needs to hand over to an agent, it can release the conversation to show subsequent messages in the Lexer Respond inbox. To do this, the chatbot simply stops calling the Claim and close API endpoint, and all new messages from the customer appear in the Respond inbox alongside other conversations for your team to pick up.

Authentication

To begin, you must create a new Bot User in Manage > Team > Our Team. Once created, you can click on the bot user in your team list to open the user's details and view examples of the bots API calls, as well as its unique API token. 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 and close

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 Respond workflow. To handover a conversation to your team, the chatbot should be configured to stop calling the API. 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://hub.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: Echo response

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://hub.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>"
}'

Facebook API 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 ParameterMessenger APITypeComments
object_id message.midStringID for the message being actioned.
published_at timestampString or integerCan be an epoch eg. 1458692752478 or an ISO8601 date eg. “2017-08-01t05:29:44Z”
source facebookStringAlways “facebook”
state closedStringAlways “closed”
account_id recipient.idStringFacebook page ID
client_id n/aIntegerID of the Lexer client, found with the access token associated with the Bot User in Lexer Hub. Must be used in the URL.

API Response Codes

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

StatusBodyDescription
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 responseInvalid 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”.