Chatbot Integration

Intro

Companies like Slack, Microsoft, and Facebook have spurred a lot of hype around the concept of “chatbots”. The extent to which the AI chatbots will deliver on their promises remains to be seen. The expectations range from personal assistants to customer service agents - or even dominators of the human race.

At Userlike, it’s mainly customer service that we’re interested in. And we’re pretty sure that no AI-system will match the power of human-to-human contact in this area any time soon. However, we still see a purpose for service bots. That's why we want to show you how easily you can create your own service bots and integrate them with your Userlike account, using our chat infrastructure.

TopicDescription
Chatbot integrationHow to integrate your chatbot into our infrastructure
Chatbot HTTP APIDetails of the chatbot HTTP API protocol
Chat commandsChat commands your chatbot can use
Chatbot chat overviewMonitor your chatbot's chat activity
Chatbot ProjectsIdeas for your first chatbot project
Sample CodeSample code for chatbots

Chatbot integration

We assume that you already have a chatbot (framework) up and running that you now want to connect to the Userlike chat infrastructure. We also assume that your chatbot (framework) is reachable via HTTP. All you have to do now is to create a "proxy" bot Operator in our Dashboard: think of it as your chatbot's representative (or ambassador) in the Userlike chat infrastructure.

Setting up a bot Operator is just as easy as setting up a regular Operator. In your Dashboard, go to "Config" and click "Operators". You will see a table with all your existing human Operators. Beneath it, under "Bots", there's a (still empty) table for all your bot Operators. Click "Add Bot" to create your first chatbot:

Now you can configure your new bot Operator:

The first name, last name and Operator Group settings are identical to those of a regular human Operator. The chat endpoints and bot behavior modes are explained below.

HTTP chat endpoints

Your chatbot (framework) can provide up to three HTTP endpoints for the Userlike chat server to call. While the "Chat message" endpoint is required, you can provide the "Chat start" and "Chat end" endpoints if they help with your specific setup.

HTTP EndpointDescription
Chat start endpointWill be called by the Userlike chat server when a Webvisitor starts a new chat with your bot. Your response will be sent to the Webvisitor.
Chat message endpointWill be called by the Userlike chat server for each message the Webvisitor sends to your bot. Your response will be sent to the Webvisitor.
Chat end endpointWill be called by the Userlike chat server when the chat session with your bot ends. No response is expected.

We'll explain the HTTP API (the expected request/response protocol) of these endpoints in detail further below.

Bot behavior modes

You can configure your chatbot in four different behavior modes. These modes decide in which situations your Webvisitors will be connected to the chatbot, or if its human colleagues are the preferred choice.

Bot behavior modeDescription
Service TimeThe bot is online only outside of the Service Time defined on the Chat Widget. During Service Time, all chats go to your human Operators.
FailoverThe bot is always online but only takes chats when no other Operators are free.
HumanThe bot is always online and takes chats exactly like a normal human Operator.
FirewallThe bot is always online and takes all chats (e.g. to pre-categorize and forward them).

After you have configured and saved your new chatbot, it appears in the bot overview, just beneath the human Operator table.

From here you can edit it just like any other Operator.

If you edit an existing chatbot, you can additionally change its profile picture and define how many concurrent chat slots your bot should handle.

XMPP integration

If you are still connecting to our infrastructure via XMPP, you can find the specifics in our Chatbot XMPP Tutorial. Note that this way of integrating your chatbot with Userlike requires more technical knowledge.

Chatbot HTTP API

First we give you an overview on request/response values for your three HTTP endpoints. Further below we describe the JSON exchange format in more detail and explain how your chatbot (framework) must use it for maintaining state for each chat with your Webvisitors.

With one exception, all requests to and responses from your chatbot (framework) must use the HTTP POST method - only the first request to the "chat start endpoint" will be made using the HTTP GET method (without parameters). It is possible that in the future we'll use the POST method for the first request as well, so best make your endpoint accept both methods.

HTTP EndpointDescription
Chat start endpointWill be called by the Userlike chat server when a Webvisitor starts a new chat with your bot. Your response will be sent to the Webvisitor.
Request formatGET - without parameters
Response formatPOST - with body containing "answers" and "context" JSON formats:
{
    "answers": ["Each item", "appears as separate chat bubble"],
    "context": {"context_item": "..."}
}
Chat message endpointWill be called by the Userlike chat server for each message the Webvisitor or chat server sends to your bot. Your response will be sent to the Webvisitor.
Request formatPOST - with body containing "input" and "context" JSON formats:
{
    "input": "Message sent by Webvisitor",
    "context": {"context_item": "..."}
}
Response formatPOST - with body containing "answers" and "context" JSON formats:
{
    "answers": ["Each item", "appears as separate chat bubble"],
    "context": {"other_item": "..."}
}
Chat end endpointWill be called with a POST request by the Userlike chat server when the chat session with your bot ends. No response is expected.
Request formatPOST - with body containing the "context" JSON format:
{
    "context": {"other_item": "..."}
}
Response formatNo response expected
JSON exchange format

The body of each POST request/response must contain a JSON object. There are three different JSON formats that can make up this object: "input", "answers" and "context". While "input" and "answers" are mutually exclusive, the "context" object must be always provided.

JSON formatDescription
answersSent from your chatbot, "answers" can either be a single string or an array of strings or objects. If an array is provided, each item will appear in a separate chat bubble in your Webvisitor's chat. Example:
"answers": ["First message sent to Webvisitor", "Second message"]
"answers": "Only one message sent to Webvisitor"
"answers": [
    "The next message is a command",
    {"command": "push", "value": "/about"}
]
inputSent to your chatbot, "input" contains your Webvisitor's chat message as a single string. Example:
"input": "Incoming message from Webvisitor"
contextSent from your chatbot and repeated in the response from our chat server, "context" can be any valid JSON object you need. Example:
"context": {
    "state": "askname",
    "session_info": {
        "id": "abcdef"
    }
}
Maintaining state

We have seen that the JSON body of each POST request/response must contain a "context" object. Initiated by the first response from your chatbot (framework), all further requests from our chat server to your chatbot will always echo the last "context" object your bot provided.

You can use this echoed "context" object to keep track of the chat's state in your chatbot (framework). A short example:

Request/ResponseJSON body
First request by our chat server when new chat starts-
First chatbot response sets state in context
{
    "answers": ["What is your name?"],
    "context": {
        "state": "askname"
    }
}
Next chat server request echoes initial state in context
{
    "input": "John Doe",
    "context": {
        "state": "askname"
    }
}
Next chatbot response updates state in context
{
    "answers": ["And your email address?."],
    "context": {
        "state": "askemail"
    }
}
Next chat server request returns updated state in context
{
      "input": "john.doe@userlike.com",
      "context": {
          "state": "askemail"
      }
  }

So, with each request to your chatbot (framework), our chat server 'reminds' it in which state the current chat session is. Please note that this is just an example and you can set different properties to the "context" object: everything you set on it will be echoed by our next request.

Chat Commands

Once your bot is integrated into the Userlike chat infrastructure, it can interact with your Webvisitors. Even better though, it has access to the Userlike chat commands, giving it full control over the initiated chat session. So your chatbot can collect and store data from your Webvisitors, send them to special parts of your web page or forward the current chat session to a human colleague.

You can send a Userlike chat command like a regular message. Alternatively, you can send commands as JSON objects. It must contain a member "command" containing the name of the command, without the leading "$". If the command requires an argument, it must be provided in the member "value", unless specified otherwise.

{
    "answers": [
        {
            "command": "screenshot"
        },
        {
            "command": "push",
            "value": "/about"
        }
    ]
}

The following commands are currently available, allowing for powerful automation patterns:

CommandDescription
$screenshotTake screenshot of Webvisitor's browser
$forwardForward chat to a another Operator
$forward.jsonForward chat to a another Operator (with JSON response)
$groupForward chat to a another Operator Group
$group.jsonForward chat to a another Operator Group (with JSON response)
$anyForward chat to the next available Operator
$any.jsonForward chat to the next available Operator (with JSON response)
$nameSet name for Webvisitor
$additional01Set additional value 1
$additional02Set additional value 2
$additional03Set additional value 3
$emailSet email for Webvisitor
$localeSet locale for chat session
$noteAdd a private note to the chat transcript
$sendSend chat transcript via email to the Webvisitor when the chat session has ended
$dispatchSend current chat transcript to specified email address
$pushSend Webvisitor to a local URL
$downloadOffer Webvisitor given download
$blockBlock Webvisitor from chat
$imageSend an image to Webvisitor.

You must provide a URL to the image as first argument.
$image https://example.com/image.png
Optionally, you can provide a URL to a thumbnail image.
$image https://example.com/image.png https://example.com/thumbnail.png
You can provide an optional title, which must be enclosed in double quotes.
$image https://example.com/image.png "This is an example image"
You can also provide both a thumbnail image and a title.
$image https://example.com/image.png https://example.com/thumbnail.png "This is an example image"

Instead of encoding the command as a string, you can send a JSON object:
{
    "answers": [
        {
            "command": "image",
            "url": "https://example.com/image.png",
            "thumbnail_url": "https://example.com/thumbnail.png",
            "title": "This is an example image"
        }
    ]
}

The members "thumbnail_url" and "title" are optional.
$videoSend a video to Webvisitor.

You must provide a URL to the video as first argument.
$video https://example.com/video.mp4
Optionally, you can provide a URL to a thumbnail image.
$video https://example.com/video.mp4 https://example.com/thumbnail.jpg
You can also provide an optional title, which must be enclosed in double quotes.
$image https://example.com/video.mp4 "This is an example video"
You can also provide both a thumbnail image and a title.
$image https://example.com/video.mp4 https://example.com/thumbnail.jpg "This is an example video"

Instead of encoding the command as a string, you can send a JSON object:
{
    "answers": [
        {
            "command": "video",
            "url": "https://example.com/video.mp4",
            "thumbnail_url": "https://example.com/thumbnail.jpg",
            "title": "This is an example video"
        }
    ]
}

The members "thumbnail_url" and "title" are optional.

Note: You have to ensure that the video is encoded in a format supported by all web browser.
$chipsSend a list of predefined answers.

You must provide the list of options separated by semicolon.
$chips Yes;No;Maybe later
You can also provide a separate label for each answer.
$chips Yes:Yes please!;No:No thanks!;Maybe later You can provide an optional title, which must be enclosed in double quotes.
$chips Yes;No;Maybe later "Would you like to buy this product?"
Note: if your options contain the special characters ";", ":" or "\", you have to escape them with a "\".
$chips Yes:Yes please!;No:No thanks!;Maybe later:My answer is\: maybe

Instead of encoding the command as a string, you can send a JSON object:
{
    "answers": [
        {
            "command": "chips",
            "choices": [
                {"title": "Yes"},
                {"title": "No"},
                {"title": "Maybe later", "message": "My answer is: maybe"}
            ],
            "title": "Would you like to buy this product?"
        }
    ]
}

When sending the command as JSON object, no special escaping is necessary.
$quitQuit chat
![macroname]Send given text macro

If you want to receive success and error feedback for regular chat commands (e.g "$any" ) back into your bot interface you need to enable this option in the bot Operator config, otherwise these messages are not routed back into the bot interface.

If a JSON command was provided, the corresponding response object will have the following format:

{
type: "info|error",
status: "OperatorStatsError|OK|OperatorNameNotFound|OperatorNotFound|SelfForwardError|OperatorBusy|OperatorNotAvailable|GroupNotFound|GroupNameNotFound|AllOperatorsBusy",
message: "...",
data: {...},
}

 

See the code sample below for more details on how to integrate these commands with your bot logic.

Chatbot chat overview

While we welcome automation for many tasks, we still want to monitor our trusted chatbot's activity. They are our loyal servants after all - or aren't they? Thankfully, all of your chatbot's activity is available via transcripts in your Userlike Dashboard, just like with any human Operator.

Continuing our simple example from above, the following interaction of a Webvisitor with your chatbot...

... shows up like every other chat transcript in the Userlike Dashboard:

You can easily filter all your chatbot's interactions for regular audits and check that it does its job as expected. Filtered results also include interactions that were only initiated by your chatbot and then switched to a human Operator, so you truly have a full overview.

Chatbot Ideas

We have compiled some ideas for worthwhile customer service chatbot projects that you can integrate with the Userlike chat infrastructure.

A simple service chatbot

A service chatbot is at the front line. It waits for Webvisitors, greets them and collects required data for better customer service. Once it has done its job, it forwards the Webvisitor to its human colleagues.

While we provide you with our built-in service chatbot Chat Butler, you can create your own version with more advanced features to better fit your use case.

Stuff a service chatbot can do for you
Address your Webvisitors using your predefined Userlike macros
{
    "answers": ["!hi", "!welcome"],
    "context": {...}
}
Set your Webvisitor's email address
{
    "answers": ["$email %s" % email_from_input],
    "context": {...}
}
Set your Webvisitor's name
{
    "answers": ["$name %s" % name_from_input],
    "context": {...}
}
Forward your Webvisitors to any free human Operator
{
    "answers": ["$any"],
    "context": {...}
}
A "deal" bot

The deal bot offers your customers to check for special deals.

Stuff a deal bot can do for you
Proactively ask Webvisitors if they are interested in special deals
{
    "answers": ["Want me to check for special deals?"],
    "context": {...}
}
Return shop API results to Webvisitor
{
    "answers": [
        "Best deal: http://deal-url",
        {
            "command": "chips",
            "title": "Interested?"
            "options": ["Yes", "No"]
        }
    ],
    "context": {...}
}
Evaluate Webvisitor's response and push to product URL
{
    "answers": ["Here you go!", "$push http://deal-url"],
    "context": {...}
}
A route bot

The route bot provides your Webvisitors with real-time information on how to reach your business or event with public transport. Based on a location provided by your Webvisitor it queries 3rd-party services (like Berlin + Brandenburg public transport service (VBB) and provides them with the itinerary from the closest station to your store, timetables included.

Stuff a route bot can do for you
Request your Webvisitor's location
{
    "answers": ["Where are you right now?"],
    "context": {...}
}
Return 3rd party API results to Webvisitor
{
    "answers": ["Take line %s at station %s." % (line, station)],
    "context": {...}
}
Render map to next station and send to Webvisitor
{
    "answers": [
        "$image %s \"Route to the next station\"" % map_image_url,
        "Here is also a link to Google Maps: %s" % google_map_url],
    "context": {...}
}

Have we sparked your interest? We are curious to learn what kind of chatbot service you (plan to) build and integrate with Userlike! Leave a comment, contact us on Facebook or Twitter or drop us a line via mail.

Sample Code

We have started a Github repository to provide you with some complete code examples. Here is a full example for a (simple) chatbot.

Further examples/pull requests are welcome!