Telerivet Developer

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

Actions are the building blocks of Custom Actions services, as well as Custom Routes. Different action types are available depending on the service type and context.

The action types that are available for each service context are listed below. Click on an action type to see its full documentation.

Message Context

Incoming message services (incoming_message_actions, message_actions)

Message Status Context

Message status services (message_status_actions)

Voice Context

Voice call services (voice_actions)

USSD Context

USSD session services (ussd_actions)

Contact Context

Contact and data row services (contact_actions, data_row_actions)

Project Context

Project-level services (scheduled_actions, project_actions)

Button Page Context

Button page services (button_page, opt_out_page)

Messaging Poll Context

Messaging poll services (messaging_poll)

Custom Route Context

Custom route rules (see Route)

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.

API Properties

type
"reply"

Required.

body
object

Required. Message body. See Message Body Properties.

route_id
string

ID of the route to send the message from. If not specified, uses the default route.

label_names
array

Array of label names to apply to the sent message.

schedule
object

Schedule to send the message at a later time.

Properties:

interval Required. Time interval type. Values: minutes, days. (string)
minutes Number of minutes (when interval is "minutes"). (number)
days Number of days (when interval is "days"). (number)

Example

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

JSON

{
    "type": "reply",
    "body": {
        "content": "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.

API Properties

type
"send_text"

Required.

body
object

Required. Message body. See Message Body Properties.

route_id
string

ID of the route to send the message from. If not specified, uses the default route.

label_names
array

Array of label names to apply to the sent message.

schedule
object

Schedule to send the message at a later time.

Properties:

interval Required. Time interval type. Values: minutes, days. (string)
minutes Number of minutes (when interval is "minutes"). (number)
days Number of days (when interval is "days"). (number)
to_number
string

Required. Phone number to send the message to. May contain template placeholders.

Example

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

JSON

{
    "type": "send_text",
    "body": {
        "content": "[[contact.name]] sent you a message: [[content]]."
    },
    "to_number": "+16505550123"
}

Send message to this contact

Sends a text message to the current contact.

API Properties

type
"send_text_to_contact"

Required.

body
object

Required. Message body. See Message Body Properties.

route_id
string

ID of the route to send the message from. If not specified, uses the default route.

label_names
array

Array of label names to apply to the sent message.

schedule
object

Schedule to send the message at a later time.

Properties:

interval Required. Time interval type. Values: minutes, days. (string)
minutes Number of minutes (when interval is "minutes"). (number)
days Number of days (when interval is "days"). (number)

Example

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

JSON

{
    "type": "send_text_to_contact",
    "body": {
        "content": "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).

API Properties

type
"send_text_to_group"

Required.

body
object

Required. Message body. See Message Body Properties.

route_id
string

ID of the route to send the message from. If not specified, uses the default route.

label_names
array

Array of label names to apply to the sent message.

schedule
object

Schedule to send the message at a later time.

Properties:

interval Required. Time interval type. Values: minutes, days. (string)
minutes Number of minutes (when interval is "minutes"). (number)
days Number of days (when interval is "days"). (number)
group_name
string

Required. Name of the group to send the message to.

exclude_sender
boolean

If true, exclude the message sender from receiving the group message.

Example

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

JSON

{
    "type": "send_text_to_group",
    "body": {
        "content": "[[contact.name]] said: [[content]]."
    },
    "group_name": "subscribers",
    "exclude_sender": null
}

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.

API Properties

type
"add_contact_to_group"

Required.

group_name
string

Required. Name of the group. If the group does not exist, it will be created.

Example

add contact to group subscribers

JSON

{
    "type": "add_contact_to_group",
    "group_name": "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.

API Properties

type
"remove_contact_from_group"

Required.

group_name
string

Required. Name of the group. If the group does not exist, it will be created.

Example

remove contact from group subscribers

JSON

{
    "type": "remove_contact_from_group",
    "group_name": "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.

API Properties

type
"set_contact"

Required.

phone_number
string

Required. Phone number for the contact to use. May contain placeholders like [[word2]].

Example

use contact with phone number [[word2]]

JSON

{
    "type": "set_contact",
    "phone_number": "[[word2]]"
}

Set contact name

Updates the name of the current contact in Telerivet.

API Properties

type
"set_contact_name"

Required.

name
string

Required. Name to assign to the contact. May contain template placeholders like [[word3]].

Example

set [[word3]] as contact name

JSON

{
    "type": "set_contact_name",
    "name": "[[word3]]"
}

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.

API Properties

type
"set_contact_var"

Required.

variable
string

Required. Name of the contact variable to set (without the contact.vars prefix).

value
string

Value to assign to the variable. May contain template placeholders like [[contact.name]].

Example

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

JSON

[
    {
        "type": "set_contact_var",
        "variable": "email",
        "value": "[[word4]]"
    },
    {
        "type": "set_contact_var",
        "variable": "birthdate",
        "value": "[[word5]]"
    }
]

Block sending to contact

Blocks the current contact.

API Properties

type
"block_contact"

Required.

send_blocked
boolean

If true, block sending messages to this contact. If false, unblock the contact. Default: true.

Example

block sending messages to contact

JSON

{
    "type": "block_contact",
    "send_blocked": true
}

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.

API Properties

type
"send_ussd"

Required.

mmi_code
string

Required. USSD/MMI code to send (e.g. *123#). May contain placeholders.

route_id
string

ID of the route to send the USSD request from. If not specified, uses the default route.

Example

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

JSON

{
    "type": "send_ussd",
    "mmi_code": "*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.

When receiving MMS and chat 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, although these settings can be configured when using Telerivet on a custom domain.

API Properties

type
"send_email"

Required.

to_email
string

Required. Recipient email address. May contain placeholders like [[contact.vars.email]].

subject
string

Required. Email subject line. May contain placeholders.

body_text
string

Required. Email body text. May contain placeholders.

reply_to
string

Reply-to email address. May contain placeholders.

include_message_attachments
bool

If true, include any attachments from the current message as email attachments.

Example

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

[[content]]

JSON

{
    "type": "send_email",
    "to_email": "admin@example.com",
    "subject": "New message from [[contact.name]]",
    "body_text": "Phone Number: [[from_number]]\n\n[[content]]"
}

Trigger service for contact

Triggers another service for the current contact.

API Properties

type
"trigger_contact_service"

Required.

service_id
string

Required. ID of the service to trigger.

Trigger service for message

Triggers another service for the current message.

API Properties

type
"trigger_message_service"

Required.

service_id
string

Required. ID of the service to trigger.

Trigger service for project

Triggers another service for the current project.

API Properties

type
"trigger_project_service"

Required.

service_id
string

Required. ID of the service to trigger.

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.

API Properties

type
"send_airtime"

Required.

provider_id
string

Required. ID of the airtime provider to use.

products
array

Required. Array of product configurations for different mobile networks or countries.

Each item has the following properties:

country Required. Two-letter country code (e.g., KE for Kenya). (string)
operator_id ID of the mobile network operator (according to the airtime provider). Required if the provider supports multiple operators. (string)
product_id Required. ID of the airtime product to send (according to the airtime provider). (string)
amount Amount of airtime to send. Required for variable-amount products. (number)
actions
array

Array of actions to execute if the contact is on a supported mobile network.

on_success
string

Name of subroutine to execute when the airtime transaction succeeds.

on_failure
string

Name of subroutine to execute when the airtime transaction fails.

Send value

Sends a digital value product to the current contact if their phone number is in a particular country. Acts like a condition, and allows running other actions if the contact is in one of the supported countries. An 'else' condition can be added below this action to handle contacts that are not in one of the supported countries.

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.

API Properties

type
"add_label_to_message"

Required.

label_name
string

Required. Name of the label to add to the message.

Example

add label support requests to message

JSON

{
    "type": "add_label_to_message",
    "label_name": "support requests"
}

Star message

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

API Properties

type
"star_message"

Required.

Example

star this message

JSON

{
    "type": "star_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

API Properties

type
"set_variable"

Required.

variable
string

Required. Name of the variable to set (e.g. $foo, contact.vars.bar, phone.vars.baz).

value
string

Required. Value to assign to the variable. May contain placeholders like [[contact.name]].

op
string

Optional arithmetic operation to perform between value and value2. Values: plus, minus, times, div.

value2
string

Second operand for the arithmetic operation (required if op is specified).

Example

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

JSON

[
    {
        "type": "set_variable",
        "variable": "$foo",
        "value": "[[word1]]"
    },
    {
        "type": "set_variable",
        "variable": "phone.vars.bar",
        "value": "[[word2]]",
        "op": "plus",
        "value2": "[[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.

API Properties

type
"cancel_scheduled_messages"

Required.

Example

cancel scheduled message(s) to this contact

JSON

{
    "type": "cancel_scheduled_messages"
}

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.

API Properties

type
"webhook"

Required.

url
string

Required. Webhook URL to receive the HTTP POST request.

secret
string

Secret string passed as POST parameter for request verification.

Example

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

JSON

{
    "type": "webhook",
    "url": "http://www.example.com/incoming.php",
    "secret": "abcdefg"
}

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.

API Properties

type
"log"

Required.

value
string

Required. Log message content. May contain template placeholders like [[contact.name]].

Example

show log message:
word1 = [[word1]]

JSON

{
    "type": "log",
    "value": "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.

API Properties

type
"run_script"

Required.

code
string

Required. JavaScript code to execute. See Cloud Script API for available functions and variables.

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);

JSON

{
    "type": "run_script",
    "code": "var response = httpClient.request(\n    \"http://api.coindesk.com/v1/bpi/currentprice.json\");\n\nvar bitcoinInfo = JSON.parse(response.content);\nsendReply(\"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'.

API Properties

type
"condition"

Required.

conditions
array

Array of condition objects. Required unless if_mode is else.

Each item has the following properties:

type Required. Condition type. Values: is, is_not, has_word, contains, does_not_contain, starts_with, does_not_start_with, ends_with, does_not_end_with, alpha_before, alpha_after, equals, does_not_equal, less_than, greater_than, less_or_equal, greater_or_equal, contact_is_in_group, contact_not_in_group. (string)
variable Required. Variable to test, e.g. [[word1]], [[contact.name]]. Not required for contact_is_in_group and contact_not_in_group conditions. (string)
value Required. Value to compare against (or group name for group membership conditions). (string)
actions
array

Required. Array of actions to execute if the conditions match.

op
string

Operator to join multiple conditions. Values: and (all conditions must match), or (any condition must match). Default: or.

if_mode
string

Controls how this condition relates to previous conditions. Values: if (default, starts a new conditional block), else_if (only evaluated if the previous if or else_if did not match), else (executed if none of the previous if/else_if conditions matched; does not require conditions array).

Example

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

JSON

{
    "type": "condition",
    "actions": [
        {
            "type": "reply",
            "body": {
                "content": "Help is on the way!"
            }
        }
    ],
    "conditions": [
        {
            "variable": "[[word1]]",
            "type": "is",
            "value": "help"
        },
        {
            "variable": "[[from_number]]",
            "type": "contains",
            "value": "255"
        }
    ],
    "op": "and"
}

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).

API Properties

type
"stop"

Required.

Example

stop processing rules

JSON

{
    "type": "stop"
}

Skip other services

Prevents any other automated services from being triggered for this message

Example

skip other services

Copy message to project

Copies the current incoming message to another project within the same organization.

This is useful for routing messages to different projects based on message content or contact information, while keeping the original message in the current project.

API Properties

type
"copy_message_to_project"

Required.

project_id
string

Required. ID of the project to copy the message to. Must be a project within the same organization. May contain placeholders.

Example

copy message to project (invalid project)

JSON

{
    "type": "copy_message_to_project",
    "project_id": "PJxxxxxxxxxxxxxxxx"
}

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.

API Properties

type
"wait_response"

Required.

state_id
string

Required. ID of the response handler to process the contact's response.

timeout
object

Schedule for response timeout.

Properties:

interval Required. Time interval type. Values: minutes, days. (string)
minutes Number of minutes (when interval is "minutes"). (number)
days Number of days (when interval is "days"). (number)
subroutine Name of subroutine to execute if the contact does not respond within the timeout period. (string)

Example

wait for response response1

JSON

{
    "type": "wait_response",
    "state_id": "response1"
}

Skip to question

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

API Properties

type
"skip_to_question"

Required.

question_id
string

Required. ID of the poll question to skip to.

Example

skip to question q3

JSON

{
    "type": "skip_to_question",
    "question_id": "q3"
}

End survey

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

API Properties

type
"end_survey"

Required.

Example

end survey

JSON

{
    "type": "end_survey"
}

Repeat question

Within a poll service, repeats the current question again.

API Properties

type
"repeat_question"

Required.

Example

repeat question

JSON

{
    "type": "repeat_question"
}

Ignore message

Within a poll service, ignores the current message.

API Properties

type
"ignore_message"

Required.

Example

ignore message

JSON

{
    "type": "ignore_message"
}

Send reply

Sends a text reply to the sender (simple version without labels, schedule, or route configuration).

API Properties

type
"reply_simple"

Required.

body
object

Required. Message body. See Message Body Properties.

schedule
object

Schedule to send the message at a later time.

Properties:

interval Required. Time interval type. Values: minutes, days. (string)
minutes Number of minutes (when interval is "minutes"). (number)
days Number of days (when interval is "days"). (number)

Example

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

JSON

{
    "type": "reply_simple",
    "body": {
        "content": "Hello, [[contact.name]]."
    }
}

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. Alternatively, can use text-to-speech to speak a message.

API Properties

type
"play_audio"

Required.

mode
string

Required. Audio source mode. Values: file, tts.

audio_url
string

URL of the audio file to play (WAV or MP3). Required when mode is "file". May contain placeholders.

audio_title
string

Title for the audio file displayed in the web app (not played to the caller). Used when mode is "file".

text
string

Text to speak using text-to-speech. Required when mode is "tts". May contain placeholders. If mode is "file", the text is not used in the actual call but is displayed as the transcript of the file within the web app.

language
string

Language code for text-to-speech (e.g., "en-US"). Used when mode is "tts".

voice
string

Voice for text-to-speech (e.g., "man", "woman"). Used when mode is "tts".

repeat
bool

If true, repeat the audio once after a short pause.

Example

play Audio:

JSON

{
    "type": "play_audio",
    "mode": "file",
    "audio_url": "https://telerivet.com/_media/sounds/bell2.mp3"
}

Forward call

Forwards the incoming call to another phone number.

API Properties

type
"forward_call"

Required.

phone_number
string

Required. Phone number to forward the call to. May contain placeholders.

Example

forward call to +16505550123

JSON

{
    "type": "forward_call",
    "phone_number": "+16505550123"
}

Wait for key press

Waits for the caller to press a single key on the keypad, saves the input as a custom variable on the message, then triggers the associated response handler.

API Properties

type
"wait_for_key"

Required.

state_id
string

Required. ID of the response handler that will be triggered when the key is pressed (e.g., "input"). Also used as the name of the variable where the pressed key will be stored (e.g. [[vars.input]]).

Example

wait for key press » input

JSON

{
    "type": "wait_for_key",
    "state_id": "input"
}

Wait for multiple digits

Waits for the caller to enter digits on the keypad, saves the input as a custom variable on the message, then triggers the associated response handler.

API Properties

type
"wait_for_digits"

Required.

state_id
string

Required. ID of the response handler that will be triggered when the response is received (e.g., "input"). Also used as the name of the variable where the entered digits will be stored (e.g. [[vars.input]].

max_digits
number

Required. Maximum number of digits to wait for.

timeout
number

Number of seconds to wait after the last key press. Default: 10.

submit_on_hash
bool

If true, submit the input when the caller presses #.

Example

wait for up to 4 digits » input
or 10 seconds after last key

JSON

{
    "type": "wait_for_digits",
    "state_id": "input",
    "max_digits": 4
}

Record audio response

Records an audio response from the caller, saves the recording URL as a custom variable on the message, then triggers the associated response handler.

API Properties

type
"record_audio"

Required.

state_id
string

Required. ID of the response handler that will be triggered when the recording is received (e.g., "recording"). Also used as the name of the variable where the recording URL will be stored (e.g. [[vars.recording]]).

Example

record audio response » input

JSON

{
    "type": "record_audio",
    "state_id": "input"
}

Hang up

Hangs up the phone call.

API Properties

type
"hangup"

Required.

Example

hang up

JSON

{
    "type": "hangup"
}

Call contact back

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

API Properties

type
"call_contact"

Required.

service_id
string

Required. ID of the voice/IVR service to use for the call.

route_id
string

ID of the route to use for the call. If not specified, uses the default route.

schedule
object

Schedule for when to make the call. If not specified, calls immediately.

Properties:

interval Required. Time interval unit. Values: minutes, hours, days. (string)
minutes Number of minutes to wait (when interval is "minutes"). (number)
hours Number of hours to wait (when interval is "hours"). (number)
days Number of days to wait (when interval is "days"). (number)

Set message variable

Updates a custom variable for the current message.

API Properties

type
"set_message_var"

Required.

variable
string

Required. Name of the message variable to set (without the vars prefix).

value
string

Value to assign to the variable. May contain template placeholders like [[contact.name]].

Example

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

JSON

[
    {
        "type": "set_message_var",
        "variable": "urgent",
        "value": "yes"
    },
    {
        "type": "set_message_var",
        "variable": "length",
        "value": "[[content.length]]"
    }
]

Run subroutine

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

API Properties

type
"run_subroutine"

Required.

name
string

Required. Name of the subroutine to run.

Example

run subroutine foo

JSON

{
    "type": "run_subroutine",
    "name": "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.

API Properties

type
"push_to_zendesk"

Required.

subdomain
string

Required. Zendesk subdomain (e.g., "example" for example.zendesk.com).

subject
string

Required. Subject line for the Zendesk ticket. May contain placeholders.

content
string

Required. Content of the Zendesk ticket. May contain placeholders.

Example

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

JSON

{
    "type": "push_to_zendesk",
    "subdomain": "example",
    "subject": "Message from [[contact.name]]",
    "content": "[[content]]"
}

Wait for response

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

API Properties

type
"wait_ussd_response"

Required.

state_id
string

Required. ID of the response handler that will be triggered when the response is received (e.g., "input"). Also used as the name of the variable where the USSD response will be stored (e.g. [[vars.input]]).

Example

wait for response input

JSON

{
    "type": "wait_ussd_response",
    "state_id": "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.

API Properties

type
"send_ussd_reply"

Required.

text
string

Required. Text to display in the USSD session. May contain placeholders.

Example

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

JSON

{
    "type": "send_ussd_reply",
    "text": "Please enter a response on the keypad."
}

End session

Ends the current USSD session.

API Properties

type
"end_session"

Required.

Example

end session

JSON

{
    "type": "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.

API Properties

type
"resend_message"

Required.

route_id
string

ID of the route to resend the message from. If not specified, uses the original route.

schedule
object

Schedule for when to resend the message. If not specified, resends immediately.

Properties:

interval Required. Time interval unit. Values: minutes, hours, days. (string)
minutes Number of minutes to wait (when interval is "minutes"). (number)
hours Number of hours to wait (when interval is "hours"). (number)
days Number of days to wait (when interval is "days"). (number)

Example

resend message

JSON

{
    "type": "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.

API Properties

type
"use_phone"

Required.

phone_ids
array

Required. Array of basic route IDs that can be used to send the message

Example

Send message from 555-0123 or 555-0456

JSON

{
    "type": "use_phone",
    "phone_ids": [
        "PN123abc",
        "PN456def"
    ]
}

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:

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. Whitespace is allowed around the filter names and parameters.

Multiple filters can be applied to the same variable in series, e.g.: [[contact.vars.example | default:"something" | urlencode]].

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.

If the default filter is used for the contact.name variable, the default value will also be returned if the contact's name is equal to the contact's phone number, since if contact's do not have a specified name it will automatically be initialized to the phone number.

Examples

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

word

Extracts the N-th word from the variable (1-9). The word filter requires a parameter, which can can be a literal number from 1-9 or another variable name that evaluates to a number from 1-9.

For example, if contact.name is "Sam Smith", then [[contact.name | word:1 ]] will return "Sam".

Example

[[contact.name | word:1 ]]
[[content | word:2 ]]

remainder

Extracts the text after the N-th word of the variable (1-9). The remainder filter requires a parameter, which can can be a literal number from 1-9 or another variable name that evaluates to a number from 1-9.

For example, if the message content is "subscribe Sam Q. Smith", then [[content | remainder:1 ]] will return "Sam Q. Smith".

Example

[[content | remainder:1 ]]

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

length

Returns the number of characters in the variable. If the variable does not have a value, returns 0.

Example

[[ content | length ]]

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.