Twilio Bot Tutorials

Introduction

In this Chatflow tutorial, we’ll show you how to program a text reversing bot for Twilio. The following video shows the bot in action:




In addition, we explain the input and output for the Twilio In and Twilio out nodes.

By the end of this tutorial, you will be able to:
  • Connect a ChatFlow app to Twilio.
  • Understand the input and output of the Twilio In and Twilio nodes
  • Debug a chatflow bot

Preparing Twilio account

Note

You can skip this section if you already have a Twilio account and/or know how to set it up.

  1. Sign up for a Twilio account. Trial accounts are free. You do not have to provide any payment details.

Note

Make sure you search for phone numbers in/close to your area and with SMS capabilities enabled.

  1. After finishing the registration, you will have to “buy” a phone number. The first phone number in trial accounts (at time of writing) is free.

A Simple Reverse Bot

1. Create a New Chatflow App with Twilio Nodes

  1. Start by opening the ChatFlow application list and add a new application. Press the “Create new App” button.
_images/twilio-new-app.png
  1. Enter a name and press “Create”.
_images/twilio-create-app.png
  1. Click on the application name on the list to edit it.
_images/twilio-edit-app.png
  1. To make your app nice and tidy, enable grid in the settings/view menu.
    _images/twilio-snap-grid.png
  2. Find Twilio In and Twilio Out nodes in the Node Library (left side) and add them to the flow.

_images/twilio-palette.png

Note

If the Twilio In and Twilio Out nodes are not in your Node Library, click on Settings in the right hand corner. A drop down will open. Click on Node Installer:

_images/settings_install_node3.png

In the Node Installer, search for Twilio. Click on the blue arrow to the right of Twilio to add the nodes into your Node Library:

_images/install_nodes_pop_up3.png
  1. Find the function node in the Node Library and add it to the flow too.
  2. Connect the Twilio In node output to the function node input and the function node output to the “Twilio Out” input, so your flow looks like this:
_images/twilio-added-connected.png

2. Configure Twilio Nodes

  1. Double click on the “Twilio in” node, and click on the displayed “Twilio receiving url” to copy it to your clipboard (highlighted in yellow).
_images/twilio-receiving-url.png
  1. In the Twilio console, go to your Phone numbers list by clicking on “Phone Numbers” on the right hand side.
_images/twilio-cp-phone-numbers.png
  1. Edit the settings for the phone number you just bought.
_images/twilio-cp-phone-list.png
  1. Paste the address you copied from the “Twilio in node” in the “A message comes in” field. Click the “Save” button.
_images/twilio-cp-add-webhook.png
  1. Go to the Twilio console dashboard (the main screen) to display your Account SID and Auth Token.

Note

You have to click the padlock icon to make Auth Token visible (the SID and token displayed in this tutorial are fake, so don’t try to use them ;) ).

_images/twilio-cp-credentials.png
  1. In ChatFlow, double click on the “Twilio Out” node. Copy Account SID and Auth Token from Twilio dashboard to this form.
  2. Enable “Respond mode” and click “OK”.
_images/twilio-out-credentials.png

Note

“Respond mode” is a quick way to enable your app to respond to incoming SMS messages (received by a Twilio In node) without having to write any extra code. When it’s enabled and you don’t redefine msg.twilio.from/to values, then those values are used in reverse, so when you use a Twilio Out node, the recipient phone number will be read from msg.twilio.in (and sender phone number will be read from msg.twilio.from accordingly). This feature also allows you to use one “Twilio Out” node with multiple “Twilio In” nodes.

3. Configuring the Function Node

  1. Double click on the function node. Fill it like in the example below:
msg.payload = msg.payload.split('').reverse().join('');

return msg;
_images/twilio-fn-reverse.png

4. Deploy the Application

  1. Hit the “Deploy” button. Now your app is running and you can test it.
_images/twilio-deploy.png

Send a text message (SMS) to the phone number you bought. Your app should respond in seconds with a message containing the text you sent, but reversed.

Basic Debugging

5. Add Debugging Functionality

  1. Add a debug node to the flow. Connect it’s input to the “Twilio in” output.
_images/twilio-debug-added.png
  1. Double click the debug node you added and set it up to log “twilio” property of “msg”.
_images/twilio-debug-edit.png
  1. Activate the debug panel and send another text message. Message details should be shown in the debug panel. You can read about those details in Twilio documentation.
_images/twilio-debug-sms.png

You can download the whole aplication here. You only have to setup Twilio In/Out nodes manually.

Twilio In and Twilio Out Nodes

Twilio In

The following fields are set in the output message:

1
2
3
4
5
6
7
8
msg = {
       twillio: {
                   from: "who.sent.the.message",
                   to: "who.is.the.message.sent.to",
                   body: "message.content"
                 }
       payload: "message.content"
     }
Variable Type Description
twilio.from String Sender phone number in E.164 format
twilio.to String Recipient phone number in E.164 format
twilio.body String Message Body
payload String Message Body (duplicate of twilio.body)

Note

The twilio property may contain other sub-properties, see the Twilio documentation for details (property names are always “camelCased” in this node output).

Twilio Out

The following is an acceptable input for Twilio Out:

1
2
3
4
5
6
7
msg = {
       twillio: {
                   from: "who.sent.the.message",
                   to: "who.is.the.message.sent.to"
                 }
       payload: "message.content"
     }
Variable Type Description
twilio.from String Sender phone number. Must be in E.164 format or an Alphanumeric Sender ID
twilio.to String Recipient phone number. Must be in E.164 format
payload String Message Body

Warning

Notice: longer messages (especially containing “high” unicode characters) may be sent in multiple parts, part arrival order is not guaranteed by Twilio.

An Advanced Twilio Bot with Session/Router Support

Creating Add Bot from Scratch

  1. Create a new app and add the following nodes:
  • Twilio In
  • Twilio Out
  • router
  • 3x enter
  • 3x state
  • 1x function
  1. Connect added nodes so the flow looks like this:
_images/twilio2-adv-connected.png
  1. Set up Twilio In/Out nodes (the previous tutorial shows how to do it).
  2. Edit the first “enter” node, name it “start”, set it as the initial state and remove the condition:
_images/twilio2-initial.png

You can leave the first state node unchanged.

  1. Edit the second “enter” node, name it “add counter”, and set it up to accept add in the payload property.
_images/twilio2-add-counter.png
  1. Edit the function node connected to the “add counter” node, name it “increase counter” and add the following code to the function body
msg.kitt.counter = (msg.kitt.counter || 0) + 1;
_images/twilio2-inc-counter.png
  1. Edit the second state node (the one connected to the function node you just edited), name it “print counter” and replace the commented out code with the following code:
msg.kitt._responses = [msg.kitt.counter];
_images/twilio2-print-counter.png
  1. Edit the third enter node, name it “end”, and set it up to accept bye in the payload property.
_images/twilio2-state-end.png
  1. Edit the third state node, name it “bye”, set “Output text” to Bye bye., leave the code as is. Make sure you check the “Dialogue ends here” option.
_images/twilio2-state-bye.png

Note

The “Twilio In” node sets up session variables automatically, so you don’t have to edit the router node. However, as messages from Twilio have no direct support for “sessions”, so you may want to tune the “idle” session length manually.

Now you can deploy the application. The finshed flow should look like this:

_images/twilio2-finished.png

Now by sending “add” message to your Twilio phone number you increase the counter (each user has own counter). By sending “bye” message, you end the conversation (and reset/kill the counter).

Note

You can download the whole sample aplication from here. You will only have to setup Twilio In/Out nodes manually.