Rules EngineTelerivet'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. |
ExampleWhen 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 EngineTo 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. |
|
Basic ConceptsWith 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 |
|
Actions |
|
Send replySends 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. | Examplesend reply: Hello, [[contact.name]]. |
Send messageSends 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. | Examplesend message to +16505550123: [[contact.name]] sent you a message: [[content]]. |
Send message to groupSends 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). | Examplesend message to group subscribers: [[contact.name]] said: [[content]]. |
Add contact to groupAdds 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. | Exampleadd contact to group subscribers |
Remove contact from groupRemoves 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. | Exampleremove contact from group subscribers |
Use another contactCreates 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. | Exampleuse contact with phone number [[word2]] |
Set contact nameUpdates the name of the current contact in Telerivet. | Exampleset [[word3]] as contact name |
Set contact variableUpdates 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. | Exampleset contact.vars.email = [[word4]] set contact.vars.birthdate = [[word5]] |
Block sending to contactBlocks the current contact. | Exampleblock sending messages to contact |
Send emailSends 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. | Examplesend email to admin@example.com: Subject: New message from [[contact.name]] |
Send airtimeSends 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 messageAdds a label to the current message. This makes it easy to segment certain types of messages on your Messages page. | Exampleadd label support requests to message |
Star messageAdds a star to the current message. This makes it easy to segment important messages on your Messages page. | Examplestar this message |
Set variableUpdates 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. | Exampleset $foo = [[word1]] set phone.vars.bar = [[word2]] + [[phone.vars.bar]] |
Cancel scheduled messagesCancels 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. | Examplecancel scheduled message(s) to this contact |
Notify webhook URLMakes 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. | Examplenotify webhook URL http://www.example.com/incoming.php |
Show log messageAdds 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. | Exampleshow log message: word1 = [[word1]] |
Run JavaScript codeRuns 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. | Examplerun 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); |
ConditionA 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'. | Exampleif [[word1]] is help and [[from_number]] contains 255 send reply: Help is on the way! |
Trigger service for contactTriggers another service for the current contact. | |
Trigger service for messageTriggers another service for the current message. | |
Stop processing rulesStops processing rules for this message (for this service only). | Examplestop processing rules |
Copy message to project | |
Set message variableUpdates a custom variable for the current message. | Exampleset vars.urgent = yes set vars. = [[content.length]] |
Wait for responseWaits 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. | Examplewait for response response1 |
Send USSD requestSends 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. | Examplesend USSD request to *104*1000*[[from_number.national_raw]]# |
Run subroutine | Examplerun subroutine foo |
Call contact backSends a voice call to the current contact. | |
Push to ZendeskPushes the message to Zendesk support. | Examplepush message to example.zendesk.com: Subject: Message from [[contact.name]] |
VariablesVariables 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. |
ExampleIncoming Message Service:send reply: Hello, [[contact.name]]! You said: "[[content]]" SMS Conversation: |
Variables for Incoming Message ServicesThe following variables are available for rule-based services that handle incoming messages:
(Click the +/- icons to expand/collapse variables)
|
|
Variables for Scheduled ServicesThe following variables are available for rule-based services that run at scheduled intervals: |
|
Running Multiple ServicesIf 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 CodeTelerivet'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 APIWhenever 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 APIWhenever 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. |