Userlike Bot Language Tutorial

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 the possibility to either integrate your own chatbot with our API or to create rule-based bot flows written in the Userlike Bot Language (UBL, covered in this tutorial).

This tutorial walks you through all the details for setting up your own bots within Userlike.

The Userlike Bot Language (UBL) allows you to write bot scripts that can be used in your Widget and channels using a simple, minimal syntax.

UBL scripts are written with the YAML language. If you are not familiar with the YAML syntax, we suggest you read up on it first, as the rest of this tutorial assumes basic knowledge of YAML formatting and data types.

The basic layout of a UBL script looks as follows (each line is annotated with an explanatory comment):

Your UBL file should always start with a `config` key containing essential configuration information for your script. `config` should contain an `abort` and a `skip` parameter. The keywords you define here will be used to trigger the abort sequence, which allows the contact to immediately quit the bot flow, or to skip input steps you‘ve defined as optional.

Once you've written a script you are happy with, you can upload it to Userlike and use it with your chatbots (further information in section below).

**Please make sure to use spaces for indentation**, as tabs will be rejected during validation when uploading your script.

After uploading the script to Userlike, you are ready to test it. To do so, go to a page that contains the Widget you‘ve associated your chatbot with and start a conversation. Test all conversation paths and see if the conversation flow works as expected. If you discover something that needs adjustments, just open your `.yml` file in your favorite text editor, make adjustments and upload it again to test your changes.

In Userlike, bots are a special type of operator. You can create a new chatbot by going to Unified Messaging Team Chatbots in your Dashboard. Click on **Add chatbot** to create a new chatbot.

There are four approach modes that you can select for your chatbot, depending on how you want to use it to provide service to your contacts:

• **Service time**: The bot is online only outside of the services times defined in the Widget.
• **Backup**: The bot is always online, but only takes conversations when no human operators are available for live conversations.
• **Human**: The bot is always online and takes chats like any other operator.
• **Firewall**: The bot is always online and receives all incoming conversations (eg. to pre-categorize and forward them)

Define a time with no reply from both contact and bot after which the conversation is considered inactive. Once this happens, the bot can perform one of the following actions:

• **End conversation** and move it to **All conversations**
• **Unassign conversation** and move it to the Inbox, where any operator in your group can see and answer it.
• **Forward conversation** to an available human operator from the same group.

Note that bot conversations don’t show up in your Inbox as long as they’re active. Your operators will only be able to see them once they end, are unassigned or forwarded.

You can upload your script by clicking on the "Upload script" button. **Please upload a valid YAML file with the extension .yml**.

This is the simplest node type. The message node can be used to display text or send links to the contact. It also supports variable expansion, so it can be used to address the contact with their name, for example. Variables are expanded by wrapping them in double curly braces.

Example of a message node:

This is the node type displays media types like images and videos.

Example of a media node:

This is the node type to display buttons with clickable links. It also supports variable expansion, so it can be used to address the contact with their name, for example. Variables are expanded by wrapping them in double curly braces.

Example of a button node:

There are different types of input nodes which represent the different ways you can collect information from your contacts. The text input node is a simple way to get data from your contact by asking them to enter text into the messenger input. The text input node has several parameters that can be used to make input required or handle invalid input. For example:

Example of a text input node in which we'll also introduce the **exists** parameter (which will be explained further in this tutorial):

As we've seen in the example above, we have the ability to check for the existence of a value and trigger an action accordingly.

The `exists` parameter itself needs the argument **where**, which can have a value of either `contact` or `context`, depending on where the information is stored.

Here's an example of how an **exists** check would be performed on the contact's name:

This node is a text input node with built-in validation for email addresses. You can use the email input node to ask your contacts to provide their email address. It will automatically check if the input provided is a valid email address. Unless you make the input optional, the contact won‘t be able to proceed to the next conversation step until a valid email address is provided. As you can see in the table below, it is very similar to the text input node. It has an additional `not-valid` condition that is triggered when the email address provided cannot be validated.

Here's how you would use a simple email input node. As you can see, it's also possible to check if an email is already known for the contact:

This is a type of text input node that offers validation. Whereas the Email node can only validate email addresses, the Regex node allows you to provide a Regular expression to validate the data provided. This means it can be used for a wide range of applications, from making sure that a phone number matches a certain format to asking for dates, customer IDs or tracking numbers.

Here's how you would use the regex input node:

The bubble input node can be used to present the contact with multiple options to choose from. It displays them as buttons (or 'bubbles') that can be clicked by the contact. Alternatively, they can also choose an option by entering a number corresponding to one of the choices. For channels that don't support displaying bubbles, a text fallback can be defined which will be displayed instead.

The bubble input node is useful if you want to guide the contact closely along a determined conversation path by proposing a set of options to choose from.

A simple example:

The carousel input node is similar to the bubble input node in how it allows you to present a variety of choices that can be clicked by the contact. Instead of only presenting bubbles that can be clicked, the carousel node allows you to add an image and to add a headline and description to each option. The carousel node is perfect for providing the contact with a selection of items, for example in an online store.

The `option` map in the carousel node is slightly more complex than that of the bubble node. We've annotated the possible keys in the example below:

The list template input node is intended **primarily for WhatsApp**, though a reduced version of it will work on other channels. It is is similar to the bubble input node in that it allows you to display a variety of choices that can be clicked by contacts, but allows more extensive formatting options.

This is useful to display a larger list of **up to ten options** for the user to select from.

A simple example:

The button template input node is intended **primarily for WhatsApp**, though a reduced version of it will work on other channels. It is is similar to the bubble input node in that it allows you to display a variety of choices that can be clicked by contacts, but allows more extensive formatting options.

A button template allows you to display a few buttons combined with other content, like text and media files. Note that only **up to three** buttons are supported.

A simple example:

The API input node allows you to fetch data from, or send data to, external systems by making HTTP requests. This allows for a variety of use cases, such as fetching the status of an order or a delivery given a corresponding ID.

You can use the same text expansion capabilities we learned about in the message node to parse the response from the API and display it to the user.

As you can see, the API node only has two parameters at the top level. `api` itself takes three parameters that specify the request and response as well as what happens when the request fails or succeeds. This is described in the table below:

The following example demonstrates general use of the API node to retrieve data and display it to the user:

The received JSON object is saved to the `result` variable. We can access the data at the top level of the object by expanding the keys by wrapping them in double curly braces. The same applies to accessing the data inside the `company` object. To signal that `{{name}}` in the second instance should refer to the name of the company and not to the name of the person, you can use a section by surrounding it with `{{#company}}{{/company}}` where appropriate.

The API node also supports making POST HTTP requests, which is demonstrated below: