In this Document

Getting Started Receiving User Messages Processing User Queries Providing a Response Uniquely Tracking Users Sending Notifications

Building Service Bots

Service Bots are powerful chat bots that developers of all levels can build that provide incredible utility to users.

Novice programmers can apply skills they learn on platforms such as Codeacademy to build bots which can instantly be used by users around the world.

Advanced programmers will be able to create more immersive bots which can use external API's, store user data, and actively send notifications to users when needed - all on your stack.

Here are some other benefits the Botler platform provides:

Analytics on your bot's usage Build on your stack using API's and languages of your choice Free deployment on Botler; no charge at all for SMS capability Uniquely track users so you can store their data Reach out over SMS to a user for notifications or reminders

Getting Started

We begin making a Service Bot by clicking "Build a Bot" on your left sidebar after you sign in. You will be asked what you would like to call your bot and to choose an optional icon. You can read more on bot UX here.

Next, you will select "Service Bot" for your bot type and continue. You should add a description about your bot so that people can find it when they search.

On the final page, Botler will ask you for your endpoint URL. This is the URL that you want Botler to send a GET request to with a user query when a message comes in directed at your bot. For example, if a user messages Botler with "@YourBot remind me to be awesome", then the entire string "remind me to be awesome" will be sent to your endpoint for you to process.

If you are still confused, this infographic should clear things up.

Your endpoint will never be revealed to a user, so it could be a directory on a site you own or even the IP address of your server, if you don't have a domain.

Receiving User Messages

Suppose you have a website which provides news, called yournews.com. You want to implement a bot which will provide the top headlines for any section a user requests. You can make a new directory called "bot_directory" and make a file called "receive.php" to receive user messages to your bot. (This example uses PHP, but you can use any language you prefer.)

This means the endpoint you give to Botler is: http://yournews.com/bot_directory/receive.php
So when we receive a message for you bot, we form a GET request that looks like: http://yournews.com/bot_directory/receive.php?q=I%20need%20sports%20news&user=1a79a4d60de6718e8e5b326e338ae533

Parameters we provide

q The complete, unaltered user query that is meant for your bot. This value will be empty if the user simply pinged your bot with no query (e.g. "@YourBot").
user An unique user identifier so you can keep track of conversation state or store data. This value will be "none" if the user does not have a Botler account.

Your receive.php file will start looking like this:

receive.php

<?php

# receive.php example

$q = url_decode($_GET['q']);
$user_id = $_GET['user'];

# Rest of your code...
# Please remember to properly escape incoming data

?>

Processing User Queries

One of the greatest advantages Botler provides is that it allows bot creators freedom to add any amount of sophistication to a bot, using whatever tools you are comfortable with.

To process user queries, one option is to implement very simple natural language processing where you check for keywords:

receive.php (fragment)

...
$news_type = "recent";

$sections = array("tech", "sports", "politics");

foreach ($sections as $sec) {
    if (strpos($q, $sec) !== false) {
        $news_type = $sec;
    }
}
...

However, if you would like users to have a more conversational exchange with your bot that goes beyond keyword matching, you can implement any depth of natural language processing (NLP) and query understanding you want.

Since your bot is on your server, you can also integrate with any AI/ML API's that you prefer.

Providing a Response

Once you have understood what the user wanted and have the relevant information to return (either by accessing your own database or some external API), you are ready to respond to the user.

For Botler to correctly read your response, your endpoint file must print out (not return) a JSON string of this structure:

{"status":"success", "response_string":"YOUR RESPONSE"}

Tip: To make sure you are printing out the string in the correct format, simply go to your endpoint URL in your browser and make sure the browser prints the JSON in the correct format. If you don't see anything on the screen, your file is not printing the string.

Here is how the end of our receive.php file might look:

receive.php (fragment)

...

# You can generate a response by processing the query
# and retreiving relevant data

$response = yourFunctions($q, $user_id);

$return_value = array('status' => 'success', 'response_string' => $response);

echo json_encode($return_value);

?>

receive.php (browser output)

{"status":"success", "response_string":"This string will be your response to the user..."}

Note: Make sure you use your language's JSON encoder to contruct the JSON string so that all characters (such as newlines) are properly escaped. This means using json_encode() in PHP, json.dumps() in Python, etc.

Optional: Uniquely Tracking Users

Botler provides you with the ability to uniquely track users who message your bot.

This is not necessary for every bot. For example, if you make a bot for weather then you may not need to track users uniquely.

However, we believe having this ability dramatically increases the utility of some bots. It also allows bot developers who invest heavily in NLP to have more meaningful and coherent conversations with users.

Suppose we have a simple bot which tracks the pushups a user does in a workout session. Let us call it @PushupBot, and your endpoint is www.example.com/my_bots/pushup.php

A user can send a message to @PushupBot in which they simply log a number for their last pushup count. To be more robust, we will assume they can also provide a sentence with the integer value somewhere in the string.

That way, a user can message us either:

@PushupBot 23 @PushupBot I did 23 pushups today
And we will log 23 pushups for this user. Here is how pushup.php may look:

pushup.php

<?php

# Connection variable stored in my_variables.php
require_once("my_variables.php");

$q = url_decode($_GET['q']);
$user_id = $_GET['user'];

# We first sanitize the inputs
$q = mysqli_real_escape_string($con, $q);
$user_id = mysqli_real_escape_string($con, $user_id);

# Now we extract the integer from the query
$int = intval(preg_replace('/[^0-9]+/', '', $q), 10);

# We insert the user and pushup count into our database table
$sql = "INSERT INTO pushups (user_id, pushup_count)
        VALUES ('$user_id', '$int')";
mysqli_query($con, $sql);
mysqli_close($con);

# Build the response
$response = "Nicely done! I have logged your pushups.";
$return_value = array('status' => 'success', 'response_string' => $response);

# Print the response
echo json_encode($return_value);

?>

And with just a few lines we have made a simple bot which can log pushups for users. Of course, there are major refinements to be made:
•   Adding a welcome message if query is empty •   Allowing phrases which return the last 10 (or any number of) pushups a user logged •   Error handling in case the user message does not match expectations
You can read more about designing an awesome bot user experience here.

Optional: Sending Notifications

Another powerful option we provide bot builders is the ability to send notifications to users. This allows you to reach out to users with reminders, updates, etc. which go right to their phones. For example, the pushup bot may want to send a message to users who don't log pushups for over a day, reminding them to do pushups!

In order to send a notification, you make a GET request to the Botler notification endpoint with the following parameters:

https://heybotler.com/listener/notify/

Parameters you must provide

bot_name The name of your bot that is sending the notification.
bot_key This is the authentication key for your bot. It can be found at the bottom of your bot page (the bottom of the bot analytics and edit page) and is unique for every bot.
user This is the unique identifier of the user you would like to send the message to.
message The content of the message you would like to send.

Note: For you to notify a user (using their identifier), it is necessary that the user must have talked to your bot at some point. For security, we do not allow a bot to send notifications to a user who has never once used it.

The endpoint will print out one of three possible results as a JSON string.

If the parameters check out and the notification is sent, the endpoint prints out: {"result":"success","server_response":"notification sent to user"}
If parameters are valid but the user has blocked notifications from this bot (please follow our UX guidelines to avoid this), the endpoint prints out: {"result":"error","server_response":"user has blocked notifications from this bot"}
Lastly, if there was anything wrong with the parameters passed - bot_name/bot_key mismatch, no user found, etc. - the file will output: {"result":"error","server_response":"invalid parameters"}

Note: A user blocking notifications simply means you cannot actively send messages to a user. The user can still message your bot and your responses will be delivered to them.

Close

How Service Bots Work

Service Bots let you serve dynamic content to users.

WeatherBot

For example, a bot which users can use to find the weather for a zip code.

When you make a Service Bot, you specify an endpoint URL where you want to receive and process queries.

Users anywhere, on any device, can submit queries to your bot.

@WeatherBot weather in 03062

@WeatherBot weather in 02215

We continuously receive user messages.

And we check if your bot is requested. If it is, we lookup your endpoint in our database.

We send the entire query to your specified endpoint by a GET request.

GET request

@WeatherBot
weather in 02215

http://yoururl.com/
?q=weather%20in%...

You can serve the query however you choose.

You can use any language, and call any API - it's your server.

weather in 02215

</>

You can begin by processing the string. Since this is your stack, you can use whatever language you prefer.

weather in 02215

Once you process the query, you can use other API's if needed - in this case a weather provider.

JSON Response

{}

Once you have generated the response for the query, you simply return a JSON response for us to read.

Once we get your response, we make sure it gets to your users.