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:
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.
When a new SMS is received:
if [[word1]] is join
add contact to group Subscribers
send SMS reply:
Thanks for subscribing!
else if [[word1]] is stop
remove contact from group Subscribers
send SMS reply:
send SMS 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:
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.
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
Send SMS reply
Sends a SMS 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.
send SMS reply:
Sends a SMS 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.
send SMS to +16505550123:
[[contact.name]] sent you a message: [[content]].
Send SMS 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).
send SMS 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.
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.
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.
use contact with phone number [[word2]]
Set contact name
Updates the name of the current contact in Telerivet.
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.
set contact.vars.email = [[word4]]
set contact.vars.birthdate = [[word5]]
Block sending to contact
Blocks the current contact.
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 (pre-4.2) with the Telerivet USSD Expansion Pack installed. Also, Telerivet cannot automatically invoke USSD requests that return menus or prompts.
send USSD request to *104*1000*[[from_number.national_raw]]#
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.
send email to email@example.com:
Subject: New message from [[contact.name]]
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.
Posts a status update (tweet) to your Twitter account.
post Tweet as example:
[[contact.name]] said: [[content]]
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.
add label support requests to message
Adds a star to the current message. This makes it easy to segment important messages on your Messages page.
star this message
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.
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.
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.
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.
show log message:
word1 = [[word1]]
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.
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);
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:
A single "If ... then ..." rule can contain multiple conditions, joined together with either 'and' or 'or'.
if [[word1]] is help
and [[from_number]] contains 255
send SMS reply:
Help is on the way!
Stop processing rules
Stops processing rules for this message (for this service only).
stop processing rules
Copy message to project
Set message variable
Updates a custom variable for the current message.
set vars.urgent = yes
set vars. = [[content.length]]
Trigger service for contact
Triggers another service for the current contact.
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.
wait for response response1
run subroutine foo
Call contact back
Sends a voice call to the current contact.
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:
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.
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.
Incoming Message Service:
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 this default behavior is not desired, you can easily override the default behavior by setting the
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:
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
To learn more, see the Cloud Script API documentation.