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, such as 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]].

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 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 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]]

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
  • 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!

Trigger service for contact

Triggers another service for the current contact.

Trigger service for message

Triggers another service for the current message.

Stop processing rules

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

Example

stop processing rules

Copy message to project

Set message variable

Updates a custom variable for the current message.

Example

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

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

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 (pre-4.2) with the Telerivet USSD Expansion Pack installed. Also, Telerivet cannot automatically invoke USSD requests that return menus or prompts.

Example

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

Run subroutine

Example

run subroutine foo

Call contact back

Sends a voice call to the current contact.

Push to Zendesk

Pushes the message to Zendesk support.

Example

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

Variables

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

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

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

When you add or edit a rule 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]].

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 rule-based services that handle incoming messages:

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

Variables for Scheduled Services

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

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.