Rules Engine

Telerivet's Rules Engine makes it easy for both developers and non-developers to easily build automated mobile messaging services on top of the Telerivet platform.

By defining custom actions directly in your browser, you can create your own SMS service without needing programming expertise or needing to run your own servers.

Your actions are displayed in an intuitive flowchart that makes it easy for anyone to create and understand the logic. To adjust the logic flow, you simply drag and drop actions into a new position in the flowchart.

For example, you can use Telerivet's Rules Engine to:

  • Send auto-replies whenever someone sends a certain keyword
  • Add or remove contacts from groups
  • Update contact information from an incoming message
  • Forward incoming messages to email, SMS, or Twitter
  • Invoke custom code via the Webhook API or Cloud Script API

You can configure custom actions to be triggered automatically when an incoming message is received, on a recurring interval, or manually for one or more messages or contacts.



Example

When a new SMS is received:
if [[word1]] is join
add contact to group Subscribers
send reply:
Thanks for subscribing!
else if [[word1]] is stop
remove contact from group Subscribers
send reply:
Goodbye!
else
send reply:
Invalid keyword [[word1]].

Creating Services with Rules Engine

To use the Rules Engine, add a new service in your Telerivet project and click "Custom Actions", or click the button below:

Create New Service

Your service can run either when you receive an incoming message, or at a recurring interval. After you save the service, your actions will run automatically whenever your service is triggered.

Basic Concepts

With the Rules Engine, you create an SMS service by combining together basic actions and conditions:

Actions do something, such as sending an SMS reply, sending an SMS to another phone number or group, sending an email notification, or adding/removing the sender from a group.

Conditions only match certain messages, such as messages with particular SMS keywords, or messages from particular phone numbers. Each if/then condition should be associated with one or more actions to perform if the condition matches.

To perform different actions depending on the incoming message, you use variables:

Variables are properties of the current message, contact, route, service, or project; for example, the sender phone number or the first word of the SMS. Variables can be either numbers or text. Each variable has its own name, which often appears in double square brackets, like [[variable_name]].

Variable Filters are simple transformations that can be applied to a variable, such as converting it to uppercase or lowercase or replacing an empty variable with a default value. Variable filters appear after a | character in double square brackets, like [[variable_name | filter_name | another_filter:param_value ]].

Actions

Send reply

Sends a text reply to the sender.

Optionally, the reply can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.

Example

send reply:
Hello, [[contact.name]].

Send message

Sends a text message to any phone number.

Optionally, the message can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.

Example

send message to +16505550123:
[[contact.name]] sent you a message: [[content]].

Send message to this contact

Sends a text message to the current contact.

Example

send message:
Hello, [[contact.name]].

Send message to group

Sends a SMS message to a group defined on your Contacts page.

Optionally, you can exclude the message sender from receiving the message (common when implementing a group chat system).

Example

send message to group subscribers:
[[contact.name]] said: [[content]].

Add contact to group

Adds the current contact to a group. If the group doesn't exist yet, Telerivet will create it.

If you want to add a contact other than the one who sent the message, add a "Use another contact" rule before this rule.

Example

add contact to group subscribers

Remove contact from group

Removes the current contact from a group.

If you want to remove a contact other than the one who sent the message, add a "Use another contact" rule before this rule.

Example

remove contact from group subscribers

Use another contact

Creates or retrieves a contact with a particular phone number, and sets that as the "current" contact for subsequent rules.

This rule is often used to allow your organization's workers to register other people via SMS, and is typically combined with other rules to add the contact to a group and update their contact information.

Example

use contact with phone number [[word2]]

Set contact name

Updates the name of the current contact in Telerivet.

Example

set [[word3]] as contact name

Set contact variable

Updates custom contact information for the current contact (for example, email address or birthdate).

The rules editor lists the current variable names available for your project. You can also use a new variable name consisting of letters, numbers, and underscores.

Example

set contact.vars.email = [[word4]]
set contact.vars.birthdate = [[word5]]

Block sending to contact

Blocks the current contact.

Example

block sending messages to contact

Send USSD request

Sends a USSD request from your Android phone to your mobile network.

On some mobile networks, USSD requests can be used to check your airtime balance, transfer airtime to other phone numbers, and more.

Note that this requires a compatible Android phone running the Telerivet Gateway app. Also, Telerivet cannot automatically invoke USSD requests that return menus or prompts.

Example

send USSD request to *104*1000*[[from_number.national_raw]]#

Send email

Sends a plain-text email with custom subject line and body.

Each rule can only send to a single email address; if you need multiple recipients, we recommend setting up a mailing list on your own server.

For MMS messages, you can optionally send the multimedia files as email attachments.

To prevent abuse, it isn't possible to change the 'From' name or email address of the email.

Example

send email to admin@example.com:
Subject: New message from [[contact.name]]
Phone Number: [[from_number]]

[[content]]

Trigger service for contact

Triggers another service for the current contact.

Trigger service for message

Triggers another service for the current message.

Trigger service for project

Triggers another service for the current project.

Send airtime

Sends airtime to the current contact if they are on a particular mobile network. Acts like a condition, and allows running other actions if the contact is on one of the supported networks. An 'else' condition can be added below this action to handle contacts that are not on the supported mobile networks.

Add label to message

Adds a label to the current message. This makes it easy to segment certain types of messages on your Messages page.

Example

add label support requests to message

Star message

Adds a star to the current message. This makes it easy to segment important messages on your Messages page.

Example

star this message

Set variable

Updates the value of any writable variable within the Rules Engine.

Optionally, you can use this rule to perform simple numeric operations between two variables such as addition, subtraction, multiplication and division.

Read-only variables cannot be updated via this rule.

See available variables

Example

set $foo = [[word1]]
set phone.vars.bar = [[word2]] + [[phone.vars.bar]]

Cancel scheduled messages

Cancels all scheduled messages to the current contact.

Note this doesn't cancel messages that are scheduled to an entire group. In this case, the contact would need to be removed from the group in order to cancel the message.

Example

cancel scheduled message(s) to this contact

Notify webhook URL

Makes a HTTP POST request to a URL on your server, passing several POST parameters with information about the current message and contact.

Your webhook script may optionally return a JSON response with a 'messages' property containing an array of messages to send, and a 'variables' property containing variable names and values to update.

For details, see the Webhook API documentation.

Example

notify webhook URL http://www.example.com/incoming.php

Show log message

Adds a log message to Telerivet's service log.

To view the service log, open your Services page and click More > View logs.

When using the "Test Service" feature, log messages will be displayed directly in the simulated phone dialog.

Example

show log message:
word1 = [[word1]]

Run JavaScript code

Runs custom JavaScript code on Telerivet's servers using Telerivet's Cloud Script API.

This makes it possible to define custom actions such as calling the Telerivet REST API or third-party APIs, or parsing structured data from incoming messages.

For more details, see the Cloud Script API documentation.

Example

run JavaScript code:
var response = httpClient.request(
    "http://api.coindesk.com/v1/bpi/currentprice.json");

var bitcoinInfo = JSON.parse(response.content);
sendReply("1 BTC = $" + bitcoinInfo.bpi.USD.rate);

Condition

A rule that only matches if a certain condition is true (e.g. the message has a particular keyword or sender). Always combined with one or more other rules.

"If ... then ..." rules can use the following types of conditions:

  • is
  • is not
  • has word
  • does not have word
  • contains
  • does not contain
  • starts with
  • does not start with
  • ends with
  • does not end with
  • alphabetically before
  • alphabetically after
  • equals
  • does not equal
  • less than
  • greater than
  • less than or equal to
  • greater than or equal to
  • contact is in group
  • contact is not in group

A single "If ... then ..." rule can contain multiple conditions, joined together with either 'and' or 'or'.

Example

if [[word1]] is help
and [[from_number]] contains 255
send reply:
Help is on the way!

If none of the above ...

A rule that only matches if none of the preceding "if ... then ..." rules matched (at the same "indentation" level).

This rule is always combined with one or more other rules, and preceded by an "if ... then ..." rule.

Example

if [[word1]] is start
send reply:
Hi!
if [[word1]] is stop
send reply:
Bye!
if none of the above
send reply:
Invalid keyword [[word1]]!

Stop processing rules

Stops processing rules for this message (for this service only).

Example

stop processing rules

Skip other services

Prevents any other automated services from being triggered for this message

Example

skip other services

Copy message to project

Wait for response

Waits for a response from the current contact, then processes the response using another set of actions or conditions. Useful for back-and-forth conversations or data collection that requires the contact to send multiple messages.

Example

wait for response response1

Skip to question

Within a poll service, skips to a question outside the normal order.

Example

skip to question q3

End survey

Within a poll service, skips to the end of the survey.

Example

end survey

Repeat question

Within a poll service, repeats the current question again.

Example

repeat question

Ignore message

Within a poll service, ignores the current message.

Example

ignore message

Send reply

Sends a text reply to the sender.

Optionally, the reply can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.

Example

send reply:
Hello, [[contact.name]].

Play text to speech

Plays a text-to speech message in the voice call, using a particular language and voice.

Example

play English female:
Hello!

Play audio

Plays an audio file in WAV or MP3 format in the voice call, which may be uploaded, linked, or recorded via the Telerivet web app.

Example

play Audio:

Forward call

Example

forward call to +16505550123

Wait for key press

Example

wait for key press » input

Wait for multiple digits

Example

wait for digits » input
or 10 seconds after last key

Record audio response

Example

record audio response » input

Hang up

Hangs up the phone call.

Example

hang up

Call contact back

Sends a voice call to the current contact using a specified IVR service.

Set message variable

Updates a custom variable for the current message.

Example

set vars.urgent = yes
set vars. = [[content.length]]

Run subroutine

Triggers a set of actions which can be reused multiple times in the same service.

Example

run subroutine foo

Push to Zendesk

Pushes the message to a Zendesk support inbox, in a ticket associated with the current contact. Zendesk agents can reply directly to the Zendesk ticket to send a reply to the contact.

Example

push message to example.zendesk.com:
Subject: Message from [[contact.name]]
[[content]]

Wait for response

Prompts the user for input in the active USSD session and saves the response as a custom variable on the message.

Example

wait for response input

Send USSD reply

Shows the specified text in the active USSD session. If this action is followed by a 'Wait for response' action, the text will be displayed as part of a USSD prompt.

Example

send USSD reply:
Please enter a response on the keypad.

End session

Ends the current USSD session.

Example

end session

Resend message

Within a service triggered when a message status changes, will automatically resend the current message via the same route or a different route.

Example

resend message

Add context

Within a natural language understanding service, adds a context for the current session so that intents with that context can be matched by subsequent replies.

Example

add my-context context for next 2 messages

Remove context

Within a natural language understanding service, removes a context from the current session so that intents with that context cannot be matched.

Example

remove my-context context

Choose route(s) to send message

Within a custom route, selects one or more basic routes that can be used to send the message.

Variables

Variables allow actions to access and update information about the incoming message, the contact who sent the message, and more.

Nearly every type of action in the Rules Engine can use variables. For example:

  • If/then conditions allow your service to run different actions depending on certain variables.
  • Actions that send SMS messages allow inserting variables into the content of the message.
  • Actions that add or remove contacts from groups can use a variable for the group name.
  • The Set variable action allows you to create your own variables, and lets you perform basic numeric computations.

When you add or edit a custom action on Telerivet, there is an Insert variable... link in places where you can insert variables.

Telerivet provides a simple templating language that lets you include variables within regular text. Simply enclose the variable name in double square brackets, e.g. [[contact.name]].

You can also perform simple transformations on variables within double square brackets using variable filters, e.g. to return a default value if the variable is empty, convert a variable to uppercase or lowercase, or to replace variables within a variable.

Variables can also be used to personalize messages sent via the web or REST API.

Different variables are available depending on the context where the Rules Engine is applied. The available variables for each context are defined below.

Example

Incoming Message Service:
send reply:
Hello, [[contact.name]]! You said: "[[content]]"
SMS Conversation:
subscribe
Hello, John Smith! You said: "subscribe"

Variables for Incoming Message Services

The following variables are available for services that handle incoming messages:

(Click the +/- icons to expand/collapse variables)

Variables for Contact Services

The following variables are available for services that are triggered for a contact:

Variables for Data Row Services

The following variables are available for services that are triggered for a data row:

Variables for Airtime Transaction Services

The following variables are available for services that are triggered for an airtime transaction:

Variables for Scheduled Services

The following variables are available for rule-based services that run at scheduled intervals:

Variable Filters

Filters are simple transformations that can be applied to variables within Telerivet's Rules Engine.

To apply a filter to a variable within double square brackets, add a | (pipe or vertical bar) character after the variable name, followed by the name of the filter. Some filters require a parameter, which can be specified by adding the : (colon) character followed by the parameter value. Multiple filters can be applied to the same variable in series. Whitespace is allowed around the filter names and parameters.

The following filters are available:

default

If the variable's value is null or the empty string, returns a default value instead. The default filter requires a parameter, which can can be a literal string (in JSON format with double quotes), number, or boolean value, or another variable name.

Examples

Hello [[contact.vars.first_name | default:"there" ]]
[[contact.vars.count | default:3 ]]
[[contact.vars.example | default:contact.vars.name ]]

replace_variables

Replace variables in double square brackets with their values in the current context.

This is useful when creating custom service templates, where a service can have custom variables which themselves may contain references to variables in double square brackets.

For example, if service.vars.reply is "Hello [[contact.name]]!", and contact.name is "Example User", then [[service.vars.reply | replace_variables ]] will return "Hello Example User!".

Example

[[service.vars.reply | replace_variables ]]

lower

Converts the variable to lowercase.

Example

you said: [[ content | lower ]]

upper

Converts the variable to uppercase.

Example

YOU SAID: [[ content | upper ]]

urlencode

URL-encodes the variable so it can safely be inserted in a URL query parameter.

Example

https://example.com/path?phone_number=[[ contact.phone_number | urlencode ]]

Running Multiple Services

If your Telerivet project has multiple services turned "on" at the same time, Telerivet will apply them in the order listed on your Services page when an incoming message arrives, as follows:

  • If a service sends an auto-reply message or if it adds or removes the contact from a group, Telerivet won't run any additional services for that message.
  • Otherwise, Telerivet will continue running the next service in order.

If this default behavior is not desired, you can easily override the default behavior by setting the return_value variable within your service:

  • If the return_value variable is 1, Telerivet won't run any additional services for that message.
  • If the return_value variable is 0, Telerivet will continue running the next service in order.

To change the order that Telerivet applies services, use the up/down arrows on the Services page.

Writing Custom Code

Telerivet's Rules Engine allows you to create many kinds of SMS services without needing programming expertise.

However, some kinds of SMS services can't be built by combining the basic rules provided by Telerivet. For example, if you want to integrate your SMS service with your own database or website, or connect to a third-party data source, then the basic variables provided by Telerivet won't be enough.

In these cases, the Rules Engine provides two ways for you to run custom code:

  • The Notify Webhook URL rule lets you forward incoming messages to a script on your own server. This lets you write code in any programming language, such as PHP, Java, Python, or Ruby.
  • The Run JavaScript code rule lets you write code in the JavaScript programming language. This code runs on Telerivet's servers whenever you receive an incoming message, so you don't need your own server.

Using the Webhook API

Whenever a new message matches a Notify webhook URL rule, Telerivet will automatically notify your server by making a HTTP POST request to a particular URL, where you can write your own code to handle the message and send replies.

To learn more, see the Webhook API documentation.

Using the Cloud Script API

Whenever a new message matches a Run JavaScript code rule, Telerivet will execute your JavaScript code on Telerivet's cloud servers.

Telerivet provides several variables and functions to your JavaScript code that let you access properties of the incoming message and perform actions such as sending SMS messages or changing the contact's group membership.

In addition, Telerivet provides the capability for JavaScript code to make HTTP requests, which allows your service to interact with other web APIs. With JavaScript you can also store data on Telerivet's servers.

To learn more, see the Cloud Script API documentation.