Chatbot API BETA

Introduction

Chatbots can assist your team and take over boring and repetitive tasks such as gathering contact information, allowing your operators to focus on helping customers. They can also be useful as a way to answer simple questions after hours.

At Userlike, we believe in the power of human-to-human contact, but recognize the value service-bots can bring to messaging. This is why we offer you to either integrate your own chatbot with our API or to design your own rule-based flow using the Userlike Bot Language.

This tutorial will walk you through all the details you need to know to integrate a chatbot with our API.

TopicDescription
How to set up a chatbotHow to configure your chatbot to work with our API
Example chatbot flowHow a typical chatbot flow can look like
API OverviewHow our API works
WebhookHow our webhook calls are structured
Triggerable eventsWhat events you can trigger after receiving webhook calls
Keeping stateHow to use our API to keep state
Chatbot SessionsHow chatbot sessions work
Sample CodeSample code for chatbots

Chatbot setup in Userlike

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" chatbot in our Dashboard: Think of it as your chatbot's representative (or ambassador) in the Userlike chat infrastructure.

In Userlike, bots are a special type of operator. You can create a new chatbot by going to Unified Messaging Config Operators in your Dashboard. You'll find the "Chatbots" section below the list of human operators. Click on "Add Chatbot" to create a new chatbot.

Now you can configure your new chatbot:

The first name, last name and operator group settings are identical to those of a regular human operator. The bot type and bot behavior modes are explained below.

Bot type

If you want to create a bot that uses our Bot API, you have to select 'API' here. Alternatively you can implement some bot behavior with the Userlike Bot Language.

Bot behavior modes

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

Bot behavior modeDescription
Service TimeThe bot is online only outside of the service time defined on the 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 available.
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. After you've just added the bot, you need to edit it one time to configure the API settings.

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

Webhook URL

This is a URL hosted by you, where we can reach your chatbot via HTTP. We will call this endpoint everyt time a chat-related event happens, e.g. when a conversation starts or when a new message comes in.

API URL

This is a unique URL hosted by Userlike, which your chatbot can reach via HTTP. You can call this endpoint any time your chatbot wants to add something to the conversation that is not a direct response to a previous request made to your webhook.

Webhook URL vs. API URL

So your chatbot has two possibilities to send messages to a conversation:

  • as a direct response to a chat event that has been sent to your **Webhook URL**.
  • as a self-initiated message to your Userlike **API URL**.

In most cases you will just send a response to our calls to your webhook. But when a call makes your chatbot do something that can take a while (like asking another web service), you can acknowledge the request via a response first, and then send the final result to the conversation once it is done.

API Security Token

You need to generate a security token to use our API endpoint and add it here. Each API call you make needs the token specified as "SECURITY-TOKEN" HTTP Header Field.

Webhook Headers

You can specify HTTP Headers that will be included with each webhook request we send to you. You can use this to make sure the requests really originate from us.

Example Chatbot Flow

Lets say you have a webshop and want to automatically handle some of your customers' requests.

Contact starts a chat

After the bot is set up, you will receive a call to your webhook URL whenever a contact starts a chat with the bot.

Your bot responds to the webhook request directly and sends a welcome text message, together with a bubbles element to offer the contact some choices:

This is how it will look for the contact:

Contact selects delivery status

Once the contact clicks on "Delivery status of an order", you will receive a call to your webhook URL, containing all data from the click event.

Your bot responds by asking the contact for the order id.

Contact sends order id

When the contact sends the order id, you receive another call to your webhook URL.

Since looking up all the delivery information on the order can take a while and requires a call to another webservice, your bot schedules an asynchronous job for it. To inform the contact and not keep them waiting, the bot also sends a short info message as a direct reponse to the webhook call.

Chatbot sends result

After the asynchronous job has finished, the bot makes a self-initiated call to the Userlike "API URL", sending the result of the delivery inquiry.

Your chatbot handled your customer's request automatically, responding to all messages immediately and delivering time-consuming results once they were done.

API Overview

Whenever a contact starts a chat and your bot is selected as a conversation partner, you'll receive a webhook call with a start event. From then on you will have the cid of the chat session, which can be used to trigger events in response.

Whenever the contact writes more messages in the conversation, you will also receive more webhook calls, which will contain the same cid as the start event has.

To react to incoming events, you can trigger various events yourself. For example you can send a message or forward the conversation to a human. Those events have a similar JSON structure as the incoming ones. To trigger them you can either directly respond to the webhook call, or you can send a request to our chatbot endpoint.

Authentication and Security

We offer to specify HTTP headers when you create or edit your bot in the Dashboard (see Webhook headers), which will be sent with each webhook call. We recommend that you generate a security token and use it in the headers, so you can verify that the webhook calls really originate from us.

To authenticate on our chatbot API endpoint, you have to generate another security token, which you can also enter when you create or edit a bot in the Dashboard (see API Security Token).

Rate limits

If you use our API endpoint, please note that you can only send 20 requests that use the same cid per minute. When the limit is reached, we will respond with 429 status code.

Webhook Protocol

Whenever certain events happen, you'll receive a POST Request on your webhook, which contains JSON data describing the event.

The event data looks like this. Note that the contact and widget objects were left out to keep the sample shorter. You can find the full object below.

The info object contains general information about the chatbot session, while the packet object contains event specific information.

Info object

Those keys are inside the info object:

KeyDescription
cidUnique string identifier for the current chatbot session. You will need to include this, if you want to trigger an event in response to the webhook call.
contactInformation on the contact. If the contact is visiting your site for the first time, this will not contain much. But otherwise this might contain useful information.
contextYou can use the context object to save state for a specific bot session. You can read more about this here: How to use our API to keep state
approach_modeWhich approach mode was used to start this conversation. It is set to "proactive" if the chat opened automatically, otherwise it is set to "normal".
widgetInformation on the widget that was used to start the conversation.
Webhook Events

Those events can be inside the packet object when your webhook is called:

NameDescription
startA new chat session with a bot was started. You should use this event to send a welcome message to the contact.
messageA new message from the contact was received.
clickA contact clicked on an option of a bubble or carousel element. Please note that options are one-indexed, so the first option is referred to by 1.
How to respond

We expect you to respond with a 200 status code. You can either leave the response body empty or use the response to directly trigger some events.

Triggerable Events

To respond to the events sent to the webhook, you can trigger certain events yourself.

This is how a event looks like:

It always needs a cid specified inside the info. packet also always needs an event name. The payloaddiffers for each type of event. In this case we have to provid the content of the message under body

Events can be triggered by two in two ways:

  • You can include a list of event objects as JSON in your response to our webhook call.
  • You can also send the same JSON as a new request to our API endpoint.

Those actions are available:

NameDescription
messageSend a message to the contact.
bubblesSend a message to the contact, together with different buttons to click on. You'll receive a click event when the contact clicks on one of the buttons.
carouselSimilarly to bubbles, but with images on the buttons. You'll receive a click event as a response.
navigateMake the contact navigate to a certain URL. If the contacts browser does not allow navigation, the message from the fallback key will be sent to the contact. You can use {{link}} as a placeholder inside the fallback message, we will replace it with the target URL. Note that the target URL must have the same host as the URL the contact is currently visiting.
contact_updateUpdate the contact name, email and mobile number. You only need to provide one of name, email or mobile_number.
abortStop bot interaction and continue normal conversation flow. The conversation is visible for and can be routed to human operators.
endTerminate the bot session and set the 'ended' status on the conversation.
forward_groupTerminate the bot session and forward the conversation to any available operator from the given group.
forward_anyTerminate the bot session and forward the conversation to any available operator.

Keeping state with the context object

We allow you to keep session-specific state in our API.

On each webhook response or API request, you can provide a context, which can be any valid JSON object. Just make sure it's not bigger than 10 KB.

After you set a context, we will echo the same object in each webhook request we send to you. Note that we will completely overwrite the previous context object, if you provide a new one. If you send us an empty context, we will ignore it and keep the previous one.

Chatbot sessions

Chatbot sessions are started when a conversation is started on your widget, while a bot is configured with a matching behavior mode.

After the session starts, it stays open for a defined timeout without messages or other chat activity. The timeout can be configured in the widget settings under 'Live conversation timeout'.

Right now there is no way to resume an expired session.

Python Server Example

We prepared a Python sample server for a bot that asks for the contacts name and email, before forwarding him to a human.

This is how the bot interaction looks for a contact: