User Guide


Last Updated: May 30, 2019 01:46PM PDT
30 May 2019
  • Updated Telerivet iOS app (1.1.0) to support logging in via Google or SAML
18 May 2019
  • Updated Telerivet Mobile Android app (1.1.1) to support logging in via Google or SAML, and to allow customizing notifications via the system's notification settings screen on Android 8+
16 May 2019
  • Allow logging in to Telerivet via Google or SAML single sign-on identity provider
  • Allow organization administrators to specify allowed login methods, including disabling Telerivet password logins to force users to use Google or SAML to log in
2 May 2019
  • Allow sending a short link to an opt-out page via the [[link.optout]] variable. The opt-out page has a button that, by default, will block the current Telerivet project from sending messages to that contact.
  • Allow customizing the text and actions triggered when a user clicks the button on an opt-out page or custom button page
12 April 2019
  • Allow triggering custom actions when a contact clicks a short link, or doesn't click a short link after a certain amount of time
20 March 2019
  • [[]] is now available as a variable when sending messages
18 March 2019 28 January 2019
  • The "Block sending to contact" action also allows unblocking contacts
24 January 2019
  • Allow automatically pausing a route after it sends a particular number of messages
4 January 2019
  • The last time a contact was updated is now available on the Contacts page
8 November 2018
  • Routes now have separate queues for individual messages and broadcast messages. This makes it possible to send a large broadcast (which may take a long time to send) without delaying messages sent by services in reply to incoming messages or messages sent manually through the Telerivet dashboard.
23 October 2018
  • Allow scheduling Custom Actions services to contacts
  • REST API allows sending or scheduling services to groups
  • If the first question of a poll is edited after the poll has already been scheduled, the edits will now apply to previously-scheduled messages.
18 October 2018
  • Custom Actions services can now be triggered when message status changes
5 October 2018
  • The Message object returned by the REST and Webhook API now includes a time_updated field, showing the time the message status last changed
  • The Message export CSV includes a Time Updated column 
19 July 2018 2 July 2018
  • Contacts are automatically deleted when all of their messages are deleted, if they have no contact information besides a phone number.
28 June 2018
  • If accounts are unpaid and inactive for more than 180 days and have more than 500 stored messages, 50 contacts, or 500 data rows, those messages, contacts, or data rows will be permanently deleted after multiple email warnings if the account remains unpaid and inactive for an additional 45 days.
20 June 2018
  • If a user completes the registration process but does not start using their project within 3 years, their user account, project, and organization will be deleted.
  • If a user is invited to an existing Telerivet project or organization, but does not complete the registration process within 30 days, their user account will be deleted.
14 June 2018
  • API documentation is formatted properly when printing the documentation from the browser.
11 June 2018
  • Added REST API method to send up to 100 different messages in a single API request. When sending multiple messages, it is significantly faster than sending 1 message per API request. 
  • Added "send_broadcast" REST API method to send a single message (optionally including variables) to a group and return a Broadcast object. The old "send_multi" API method still exists, but is deprecated.
  • API clients can query messages by broadcast_id.
  • Renamed the Broadcast "recipients_str" property to "title". Broadcasts still have a "recipients_str" property for backwards compatibility, but it is deprecated.
  • Deprecated API methods for Mobile Money Receipts.
  • REST API now supports "Content-Encoding: gzip" request header for POST and PUT requests when the request body is JSON, to reduce the amount of data transmitted over the internet from the client to the server.
  • REST API now supports the "Accept-Encoding: gzip" request header, and will respond with gzip-encoded response body, to reduce the amount of data transmitted over the internet from the server to the client.
  • REST API client libraries updated to support gzip encoding of request and response body.
4 June 2018
  • API keys are now associated with an API Client that has limited permissions for a particular organization or project, instead of a user account.
  • Existing personal API keys associated with a user account still work, but new personal API keys cannot be created. Users who already had the "Access API" permission now have the "Use personal API key permission", which can be revoked when no longer needed.
  • Users with the "Project contributor" and "Project viewer" role can optionally be prevented from exporting data
  • The Developer API page shows the time each API key was last used, the IP address it was used from, and the user who created the API key.
  • API keys can no longer be viewed after they are originally created
11 May 2018
  • Renamed the "Phones" page to "Routes". "Basic Route" refers to a single Android phone, virtual number, shortcode, or other API connection. "Custom Route" refers to a route that can send messages via multiple Basic Routes.
  • API methods, parameters, and properties related to Basic Routes continue to use the term "Phone" to maintain backwards compatibility.
  • API methods, parameters, and properties related to Custom Routes continue to use the term "Route" to maintain backwards compatibility.
7 May 2018
  • External ID and Operator Reference fields are now provided for successful airtime transactions. To view these fields, click the "+" button on the Airtime page. The Operator Reference field may take up to 5 minutes to become available.
30 April 2018
  • Telerivet now sends email notifications for failed airtime transactions and airtime transactions pending payment.
  • A pre-compiled Java client library for the Telerivet REST API is now available in Maven Central
25 April 2018
  • Added REST API methods for organizations, including the ability to retrieve billing details and current usage.
23 April 2018
  • Labels can be added to outgoing messages sent via "Send SMS" actions 
  • The "Copy message to project" action now allows using a variable for the project ID. The variable contact.vars.default_shared_project_id is automatically updated each time a contact sends or receives a message via a shared phone. The action "copy message to project [[contact.vars.default_shared_project_id]]" allows messages to be copied to the appropriate project without needing the message to contain a specific keyword.
6 April 2018
  • Project Codes for connecting the Telerivet Gateway Android app are now generated on demand and automatically expire after two weeks, in order to improve security.
5 April 2018
  • Updated Terms of Service and Privacy Policy to comply with the European Union's General Data Protection Regulation (GDPR) and the Philippines' Data Privacy Act
2 April 2018
  • The "Import Messages to Send" and "Import Schedule" functions are now available when Message Review is enabled.
23 March 2018
  • When a Nexmo account is connected to Telerivet, Telerivet no longer sets the account-wide callback URL for delivery reports.
27 February 2018
  • When sending a broadcast or scheduled message to multiple groups, contacts that are members of more than one of the recipient groups will only receive the message once
  • When scheduling a message to more than one recipient, only one scheduled message will be created (instead of a separate scheduled message for each recipient)
  • Scheduled message objects returned by REST API now have recipients and recipients_str properties which work the same as broadcasts. The contact_id, group_id, and to_number fields are still provided for backwards compatibility but are only set if the scheduled message is sent to one contact or group.
7 February 2018
  • Message Review allows administrators to approve, edit, or delete messages drafted by their team before the messages are sent out
17 January 2017 11 December 2017 9 November 2017
  • Allow importing up to 1 million contacts at once via web app, and improve speed of importing contacts
19 October 2017
  • Added the current rate of sending messages to the Phone Status page (except for Android phones)
  • The Broadcasts tab shows if broadcasts are actively being sent or queued
17 August 2017
  • Organizations can specify a whitelist of IP addresses that can access the organization
10 August 2017
  • Updated Dashboard design and added new statistics:
    • Messages card shows number of incoming/outgoing messages received today for each type of message (SMS, MMS, Call, USSD)
    • Increased size of message statistics chart
    • Contacts card shows number of contacts contacted and heard from today
    • Data Tables card shows number of rows in 5 most recently updated tables
    • Airtime card shows number and cost of transactions today
    • Account balance updates in real-time
4 August 2017
  • New user permissions can be granted for users in the "Custom" role: 
    • Export project data (in order to export a particular resource such as message or contacts, the user must also have the "View" permission for that resource)
    • View user permissions
    • Edit user permissions
    • View user activity
    • Edit organization settings
  • Allow organization administrators to define a password policy for all users with access to that organization - character classes (lowercase/uppercase/number/special characters), minimum password length, and maximum age
21 July 2017
  • Message statistics can be grouped by user, phone, message type, direction, source, status, real/simulated mode, and any combination of these groups
  • Available message statistics now include message count, number of SMS parts, call duration, and price (when provided by the gateway)
  • Message statistics can be exported to CSV
3 July 2017
  • Voice polls can be configured to allow incoming calls only from the contacts that the poll was sent to (in case the contact misses the original call, and then calls the number back).
4 June 2017 9 May 2017
  • Time of day can be displayed in either 12-hour (AM/PM) or 24-hour format on the Personal Settings page. Default time format is set depending on the most common format in the user's country.
2 May 2017
  • Allow filtering log entries by action and user on the Recent Account Activity page (User Accounts > Review user activity)
  • Only create 1 log entry per minute when importing contacts/messages/rows, deleting messages, etc.
18 April 2017
  • Allow exporting scheduled messages (Messages > Scheduled > More > Export messages)
  • Email notifications can be sent when a broadcast is created (Dashboard > Edit Settings > Email Notifications)
  • Messages imported via "Import messages to send" are added to a Broadcast
6 April 2017
  • Added warnings when sending a broadcast that will take a long time to send or may cause the phone number to be blocked, or when sending a SMS poll from a phone number that can't receive replies.
  • For large broadcasts, show estimate of how long a broadcast will take to send
14 March 2017
  • Support outbound voice calls via SIP (via Twilio)
27 January 2017
  • Add support for Person-to-person calls
  • Allow triggering outbound IVR call flow in response to an incoming SMS message via Custom Actions
12 January 2017
  • Allow importing rows into custom data tables via Telerivet web app
  • Account quotas for messages and API requests now reset at midnight in the account's time zone. This timezone can be configured on the Organization Settings page. (These quotas previously included all messages / API requests from the previous 24 hours.)
19 December 2016
  • Telerivet now tracks additional statistics for each broadcast, including the number of messages in each status and the total number of SMS parts.
  • The Broadcasts tab on the Messages page shows statistics for each broadcast
  • Telerivet automatically tracks replies for broadcasts, and keeps track of the total number of replies. An incoming message is counted as a "reply" if the previous message to the same contact was an outgoing message sent as part of a broadcast in the past 7 days. If a broadcast has any replies, they can be viewed on the Replies tab for that broadcast.
  • Added REST API methods for broadcasts
  • Broadcasts that are currently being sent can be cancelled via the web or the API
  • Broadcasts can be exported to CSV
  • Added webhook when broadcast is sent
  • Projects can have multiple webhook URLs
  • Broadcasts are created when a service is manually triggered from the Contacts page for multiple contacts (if the service sends any messages)
  • Show message templates in "New Campaign" wizard
6 December 2016
  • Automatically store responses to "Custom Actions" and "Cloud Script API" services in the service's data table
2 December 2016
  • Users can now create custom script modules without needing to contact Telerivet support
  • Added GitHub integration for custom script modules that automatically update code in Telerivet when a new commit is pushed to GitHub

22 September 2016
  • Added a page to view and cancel exports of messages, contacts, and data rows. From the Dashboard page, click More > Data exports.  All users can cancel their own exports, and users with the Project administrator or Organization administrator role can also cancel other users' exports. Administrators can also see a full history of exports from all users in the project.
20 September 2016
  • Released version 3.10.9 of the Telerivet Android app, which adds "Message route fetch delay" and "Message route fetch jitter" settings (on Message Sending Parameters) to give more control over distribution of messages sent via load-balanced routes.
19 September 2016
  • In Custom Actions and Custom Call Flows, the "run subroutine" action has been added to allow reusing groups of actions within a service.
  • When a project has multiple services that handle incoming messages, certain services can be run for all incoming messages regardless of other services (for example, a webhook service can forward all messages to an external server, even messages that were handled by a poll service).
  • Messaging services now support response time limits.
    • In Custom Actions, the "wait for response" action supports a time limit with optional actions that run if the contact doesn't respond within the time limit. Services no longer have a "global" response time limit; all services previously using a global response time limit have been automatically migrated to have a time limit for each "wait for response" action.
    • The Poll service (for messaging) now supports a response time limit, with optional actions that run if the contact doesn't respond within the time limit, for example to remind the contact to answer the question. If a time limit contains an action, another time limit can be defined after the previously time limit expires (up to 3 times per question).
    • When a response timeout is generated by a service that sends an outgoing message, the timeout is only started once the message is actually sent by the gateway (which may be a while after the message is queued).
  • Cloud Script API changes
    • New Cloud Script API services now require a main() method, and stateful conversation flows should be handled via addResponseHandler . (This change does not apply to "run JavaScript code" actions, where code still runs at the top level of the script without calling main() or using addResponseHandler.) Existing scripts without a main() method will run without changes using the "backwards compatibility" setting. To upgrade an existing service, refactor the code to use main() and addResponseHandler, then disable the backwards compatibility setting under "Advanced settings".
    • Response time limits are supported in Cloud Script API services via waitForResponse and addTimeoutHandler.
    • Added helper functions for formatting phone numbers.
    • The moment timezone library has been added for manipulating dates in a local timezone.
    • Cloud Script API services and "run JavaScript code" rules run in the context of a dedicated service account, and permissions can be granted to the service account like other users (service accounts don't count as a user for service plan limits). By default, new service accounts are granted the "Project contributor" role, however projects already using the Cloud Script API have a service account in the "Project administrator" role for backwards compatibility.
  • Scheduled messages are sent in 15 second intervals, and services can schedule messages in multiples of 0.25 minutes (scheduled messages were previously only sent once per minute)
  • Scheduled messages now appear in the simulated phone when testing services
  • Limit the number of service-generated "send email" actions per day to the number of messages per day allowed by the service plan.
  • Allow adding a delay after each message sent via an SMS gateway provider.
  • When a service applied to a message generates an error, the (last) error message of the service is saved as the error message on the message itself, so that service errors are visible on the Messages page.
  • Organization administrators can delete unused organizations from the Organization Settings page, as long as the organization has no projects (or all projects have been deleted) and no billing history.
  • An email notification is sent if outgoing messages queued on a route are still queued and not assigned to any phone after several hours.
  • Voice Beta:
    • Cloud Script API now supports voice (documentation).
    • Message templates and preview are now available for text-to-speech calls.
    • Text-to-speech calls can be sent in either a male or female voice (when available)
    • Projects can set a default language and voice for text-to-speech calls.
    • Voice broadcasts can be automatically repeated once, in case the recipient didn't hear the first occurrence or in case it played during a voicemail prompt.
    • Pricing for voice calls via Nexmo virtual numbers purchased via Telerivet has been defined.
20 August 2016
  • Allow accounts with the custom domain name feature to replace "Telerivet" with their own site name in most locations in the web app
21 June 2016 17 June 2016
  • Delete custom contact variable from each contact when the field is deleted
  • Live update contact information in conversation view
  • Allow overriding user_id of message when sending messages via REST API
15 June 2016
  • Update design of Services page; show number of services on each tab
26 May 2016
  • Automatically convert en-dashes to hyphens when pasted (in addition to converting smart quotes to straight quotes) to avoid unnecessarily encoding SMS messages as Unicode
6 May 2016
  • Update design of Messages page to allow combining multiple filters
  • Allow filtering scheduled messages by label, type and date
17 March 2016 15 March 2016
  • Allow sorting fields for contacts / data tables
  • Allow showing custom contact fields and groups on Conversations tab
  • Allow customizing which field is used as lookup key when importing contacts
  • Update design of message templates dialog
  • Allow sorting and searching message templates
  • Allow showing/hiding Stats tab and Contact Name / Phone Number column for custom data tables
28 February 2016
  • Allow exporting custom message variables
  • Add "Set message variable" action
15 February 2016
  • Update Nexmo Number Insight to use "standard" API endpoint which costs EUR 0.005 instead of EUR 0.03
13 February 2016
  • Allow using parallel API connections to HTTP SMS gateway APIs to send messages faster
31 January 2016
  • Allow customizing service plan limits
  • Allow changing plan without restarting monthly/annual billing period
9 December 2015
  • Organization address field alllows users to add custom information to PDF invoices and receipts
7 December 2015
  • Stats tab on data tables page allows visualizing top responses in pie chart, bar chart, or table, as well as filtering responses
16 October 2015
  • Export up to 2,000,000 contacts, messages, data rows, receipts, or airtime transactions to CSV at once
  • Allow combining full-text search queries and filter conditions to filter contacts
  • Fltering and searching within dynamic groups
  • Search mobile money receipts by transaction ID
6 October 2015
  • PDF receipts available for all payments, and PDF invoices available for all service fees
1 October 2015
  • Filter contacts by relative date ranges (between X and Y days ago / days from now)
  • Increase volume of audio notification for new messages
30 September 2015
  • Integration with Nexmo Number Insight API to validate contact phone numbers and look up information on number type and mobile network (learn more)
19 September 2015
  • Add webhooks for message status notifications (previously only available for messages sent via REST API), contact updates, and message metadata (documentation)
  • Add new contact fields incoming_message_count, outgoing_message_count, last_incoming_message_time, and last_outgoing_message_time to REST API, Webhook API, and Cloud Script API (documentation)
  • Add URL custom field type for contacts
2 September 2015 (View blog post)
  • Drag-and-drop editor for custom actions
  • "Wait for response" action
  • "else if" and "else" conditions
  • Update design of Services page
  • Manually trigger custom actions for messages
  • Allow selecting multiple messages (e.g. failed messages) and blocking sending messages to those contacts
17 August 2015
  • Allow adding/removing contacts from one or more groups in API method to update contact (documentation)
  • Add lookup_key field to API method to update contact
31 July 2015
  • Track current and historical connectivity status for SMPP connections
28 July 2015
  • Allow performing bulk actions such as adding/removing contacts from group, deleting contacts/messages, adding/removing labels, and canceling/resending messages with up to 500,000 contacts/messages at a time (removed prompt after each 500)
  • Resend API call notifies status_url (from original API call to send messages) when message status changes
23 July 2015
  • Allow sending a SMS broadcast to up to 500,000 contacts at one time
20 July 2015
  • Filter exported messages by contact group
12 July 2015
  • Airtime topup and transfer
  • Allow sending airtime automatically in polls or rules engine
9 July 2015
  • Record duration and ring time of incoming calls in Telerivet Android app version 3.9.3
7 July 2015
  • "New campaign" wizard makes it easier to send/schedule messages to groups
22 June 2015
  • Import contacts/messages directly from .xls, .xlsx, .csv, or .txt files
  • Import up to 100,000 contacts/messages at a time
8 June 2015
  • Recommend SMS gateway providers for users that only need to send messages
10 May 2015
  • Automatically replace curly quotes/apostrophes with straight quotes/apostrophes when copying text into the Send SMS dialog in order to avoid unnecessary unicode SMS encoding and increase the number of characters available in a single SMS part
20 April 2015  (View blog post)
  • Full-text contact search
  • Advanced contact filters/segmentation
  • Dynamic groups
  • Import up to 5,000 contacts at once
  • Block sending messages to contacts
  • Custom Date/Time contact fields
  • View non-members of a group
  • Automatically track date/time contacts added to group
  • Update a custom field on multiple contacts
  • Preview messages before sending
18 April 2015
  • Allow importing Cloud Script API code from an external Git repository (see example)
20 March 2015
  • Premium plan users can customize web app logo
  • Allow accessing Telerivet web app on your own subdomain (e.g.
8 March 2015
  • Add "Send poll" rule to Rules Engine to make it easier for contacts to trigger a poll by sending a keyword
  • Messages sent to more than one contact are shown on "Broadcasts" tab on Messages page
  • When adding/editing a contact on the Contacts page, the fields shown in the add/edit contact dialog by default are the same as the visible columns, making it more convenient to add custom fields to the contact
  • Allow adding a new group when importing contacts
  • Email fields in Contacts are formatted as mailto: links
2 March 2015
  • Allow sharing one phone between multiple projects.
  • Incoming messages can be routed to other projects by using the "Copy message to project" rule in the Rules Engine (this automatically creates shared phones as necessary).
  • Add REST API method to add an incoming message
25 February 2015
  • When multiple services are active for handling incoming messages, any services where a contact has "state" will be tried first, in order of the most recent time that service was applied for that contact. This makes it easier to have multiple polls active at the same time, by preventing the situation where a contact is sent one poll, but their response could be interpreted for another poll.
  • Allow creating multiple contacts with the same phone number, and keeping track of different conversations for the same phone number. This is useful for communicating with parents on behalf of their children, when multiple siblings may share the same parent's phone number.
  • Automatically set callback URL for Nexmo delivery reports
  • Allow users without the ability to send messages to view all labels
23 February 2015
  • Add system status page at with public metrics and ability to subscribe for status updates
  • Avoid sending "Expect: 100-continue" HTTP header for webhook requests larger than 1 KB
10 February 2015
  • Allow creating services via the Rules Engine that can be applied manually to a particular contact (via the "Actions" menu on the Contacts page)
19 January 2015
  • Show message source and user account when exporting messages to CSV
11 January 2015
  • Released version 3.9.1 of Telerivet Android app which fixes bugs and hides unsupported settings on Android 4.4 and Android 5
8 January 2015
  • Allow importing scheduled messages to groups
13 December 2014
  • Released version 3.9.0 of Telerivet Android app, which supports pausing sending messages, improved support for message routes, and the ability to configure the number of times failed messages are automatically retried
  • Routes with multiple phones now keep messages in a single queue, and each phone pulls messages from the queue one-at-a-time (Previously, routes with multiple phones would immediately assign each message to a particular phone)
  • Allow pausing sending messages for each phone via webapp and API
  • Allow changing more Android app settings via "Edit Settings" page in webapp
  • Allow moving phones to a different project (via "More" link on phone page in webapp)
  • When using Message Routes, the "Resend" button and API call will send the message through the route again (not necessarily using the same phone that was used the first time)
  • Resend API allows resending messages from a different phone or route
  • When sending messages via Message Routes with multiple phones, failed messages will automatically be retried via other phones in route
1 December 2014
  • Added support for Nexmo custom sender IDs
  • Added support for Nexmo US shared event-based alerts shortcode
24 November 2014
  • Allow canceling queued messages via API and webapp
  • Added .NET client library for REST API
12 November 2014
  • Added full-text search box on Messages page to search messages by content and contact name
  • Added option to enable desktop notifications and audio notifications for new incoming messages (on Personal Settings page)
30 October 2014
  • Added from_number_e164 parameter to Webhook API for incoming messages, containing the sender ID normalized to E.164 international format (e.g. +16505550123).
29 October 2014
  • Added the ability to restore deleted messages, contacts, and other items for 7 days, via "Undo" link or via Dashboard > More > Restore deleted items. 
23 October 2014
  • Added "Time Sent" column when exporting messages
18 October 2014
  • Disabled SSL 3.0 on web and API servers in response to POODLE vulnerability
17 October 2014 11 October 2014
  • Added ability to add labels to messages when sending, scheduling, or importing them in web interface
  • Fixed bug with new group not showing up in autocomplete when sending messages from Contacts page
25 September 2014
  • Added support for two-factor authentication via smartphone app, SMS, or voice call
  • Added ability to restrict logins to whitelisted IP addresses
  • Added recent activity log to view log entries by user, organization, and project
  • Added page to view your active login sessions and log out other sessions
  • Allow OpenID login via Google Apps accounts (in addition to Gmail and Yahoo)
  • Added "Data Tables" tab to top-level project navigation
  • Prevent saving automated services with no selected phones
19 September 2014
  • Allow IP addresses in Webhook URLs
18 September 2014
  • Added support for receiving incoming MMS messages on Twilio phone numbers
15 September 2014
  • Fixed bug that could cause exporting a large number of messages to fail
8 September 2014
  • Added phone variables to Webhook API
  • Added country property to the Phone object in REST API. 
3 September 2014
  • Improved performance of Messages page for projects with large number of messages
22 July 2014
  • Increased maximum size of code in Cloud Script API to 100 KB
20 July 2014
  • Fixed bug in Cloud Script API that could cause contact groups or variables to be improperly saved
17 July 2014
  • Concatenate multipart incoming SMS from Nexmo API
15 July 2014
  • Launched new Telerivet Developer Platform with updated REST API; new client libraries for PHP; Python, Ruby, Node.js and Java; updated Webhook API; new Cloud Script API; new Zapier and Cyclos integrations; and updated developer documentation and examples.
4 July 2014 23 July 2014
  • Handle Twilio delivery status notifications
30 May 2014
  • Test numbers now generate status webhooks like other phone types
  • Allow users to have multiple API keys (to allow key rotation)
21 May 2014
  • Show warning when trying to send message to possible invalid phone number from web interface
  • Normalize recipient phone numbers to E.164 (only for newly added phones to avoid breaking existing API integrations)
  • Added variables to Rules Engine to format phone number in E.164, international, or national formats
19 May 2014
  • Simplified new user registration form and added page with followup questions

Contact Us
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found