Chatbot Integration

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.

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.

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.

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

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.

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.

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.

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.

{
    "answers": ["Each item", "appears as separate chat bubble"],
    "context": {"context_item": "..."}
}

{
    "input": "Message sent by Webvisitor",
    "context": {"context_item": "..."}
}

{
    "answers": ["Each item", "appears as separate chat bubble"],
    "context": {"other_item": "..."}
}

{
    "context": {"other_item": "..."}
}

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.

"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": "Incoming message from Webvisitor"

"context": {
    "state": "askname",
    "session_info": {
        "id": "abcdef"
    }
}

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:

{
    "answers": ["What is your name?"],
    "context": {
        "state": "askname"
    }
}

{
    "input": "John Doe",
    "context": {
        "state": "askname"
    }
}

{
    "answers": ["And your email address?."],
    "context": {
        "state": "askemail"
    }
}

{
      "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.

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:

{
    "answers": [
        {
            "command": "image",
            "url": "https://example.com/image.png",
            "thumbnail_url": "https://example.com/thumbnail.png",
            "title": "This is an example image"
        }
    ]
}

{
    "answers": [
        {
            "command": "video",
            "url": "https://example.com/video.mp4",
            "thumbnail_url": "https://example.com/thumbnail.jpg",
            "title": "This is an example video"
        }
    ]
}

{
    "answers": [
        {
            "command": "chips",
            "choices": [
                {"title": "Yes"},
                {"title": "No"},
                {"title": "Maybe later", "message": "My answer is: maybe"}
            ],
            "title": "Would you like to buy this product?"
        }
    ]
}

{
    "answers": [
        {
            "command": "links",
            "links": [
                {"title": "Google", "target": "https://google.com"},
                {"title": "DuckDuckGo", "target": "https://duckduckgo.com"},
            ]
        }
    ]
}

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.

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.

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

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.

{
    "answers": ["!hi", "!welcome"],
    "context": {...}
}

{
    "answers": ["$email %s" % email_from_input],
    "context": {...}
}

{
    "answers": ["$name %s" % name_from_input],
    "context": {...}
}

{
    "answers": ["$any"],
    "context": {...}
}

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

{
    "answers": ["Want me to check for special deals?"],
    "context": {...}
}

{
    "answers": [
        "Best deal: http://deal-url",
        {
            "command": "chips",
            "title": "Interested?"
            "options": ["Yes", "No"]
        }
    ],
    "context": {...}
}

{
    "answers": ["Here you go!", "$push http://deal-url"],
    "context": {...}
}

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.

{
    "answers": ["Where are you right now?"],
    "context": {...}
}

{
    "answers": ["Take line %s at station %s." % (line, station)],
    "context": {...}
}

{
    "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.

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!