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.
Topic | Description |
---|---|
Chatbot integration | How to integrate your chatbot into our infrastructure |
Chatbot HTTP API | Details of the chatbot HTTP API protocol |
Chat commands | Chat commands your chatbot can use |
Chatbot chat overview | Monitor your chatbot's chat activity |
Chatbot Projects | Ideas for your first chatbot project |
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 Endpoint | Description |
---|---|
Chat start endpoint | Will 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 endpoint | Will 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 endpoint | Will 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 mode | Description |
---|---|
Service Time | The bot is online only outside of the Service Time defined on the Chat Widget. During Service Time, all chats go to your human Operators. |
Failover | The bot is always online but only takes chats when no other Operators are free. |
Human | The bot is always online and takes chats exactly like a normal human Operator. |
Firewall | The 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.
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 Endpoint | Description |
---|---|
Chat start endpoint | Will 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 format | GET - without parameters |
Response format | POST - with body containing "answers" and "context" JSON formats:{ "answers": ["Each item", "appears as separate chat bubble"], "context": {"context_item": "..."} } |
Chat message endpoint | Will 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 format | POST - with body containing "input" and "context" JSON formats:{ "input": "Message sent by Webvisitor", "context": {"context_item": "..."} } |
Response format | POST - with body containing "answers" and "context" JSON formats:{ "answers": ["Each item", "appears as separate chat bubble"], "context": {"other_item": "..."} } |
Chat end endpoint | Will be called with a POST request by the Userlike chat server when the chat session with your bot ends. No response is expected. |
Request format | POST - with body containing the "context" JSON format:{ "context": {"other_item": "..."} } |
Response format | No 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 format | Description |
---|---|
answers | Sent 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"} ] |
input | Sent to your chatbot, "input" contains your Webvisitor's chat message as a single string. Example:"input": "Incoming message from Webvisitor" |
context | Sent 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/Response | JSON 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:
Command | Description |
---|---|
$screenshot | Take screenshot of Webvisitor's browser |
$forward | Forward chat to a another Operator |
$forward.json | Forward chat to a another Operator (with JSON response) |
$group | Forward chat to a another Operator Group |
$group.json | Forward chat to a another Operator Group (with JSON response) |
$any | Forward chat to the next available Operator |
$any.json | Forward chat to the next available Operator (with JSON response) |
$name | Set name for Webvisitor |
$additional01 | Set additional value 1 |
$additional02 | Set additional value 2 |
$additional03 | Set additional value 3 |
$email | Set email for Webvisitor |
$locale | Set locale for chat session |
$note | Add a private note to the chat transcript |
$send | Send chat transcript via email to the Webvisitor when the chat session has ended |
$dispatch | Send current chat transcript to specified email address |
$push | Send Webvisitor to a local URL |
$download | Offer Webvisitor given download |
$block | Block Webvisitor from chat |
$image | Send an image to Webvisitor. Details 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:
The members "thumbnail_url" and "title" are optional. |
$video | Send a video to Webvisitor. Details 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:
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. |
$chips | Send a list of predefined answers. Details 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:
When sending the command as JSON object, no special escaping is necessary. |
$links | Send a list of links with a title text. Details You must provide the list of links separated by semicolon. The URL and title of each link must be separated by a colon. $links https\://google.com:Google;https\://duckduckgo.com:DuckDuckGo Note: you must escape the special characters ";", ":" or "\" with a "\". Instead of encoding the command as a string, you can send a JSON object:
When sending the command as JSON object, no special escaping is necessary. |
$quit | Quit 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: {...},
}
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.