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:

API Response Codes

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