Tutorials
REST API
Overview Client Libraries Authentication Request Format Errors Storing Custom Data Retrieving Objects Filtering Queries Messages
Message object Broadcast object Send a message Send a message to a group Send multiple messages Query messages Remove a label from a message Add an incoming message Get custom message fields Get broadcast by ID Query broadcasts Get message by ID Add a label to a message Cancel sending a broadcast Delete a message Cancel sending a message Resend a message Update message details Update message field metadata
Scheduled Messages
ScheduledMessage object RelativeScheduledMessage object Schedule a message Query scheduled messages Update scheduled message Cancel a scheduled message Create relative scheduled message Query relative scheduled messages Update relative scheduled message Delete relative scheduled message Get scheduled message by ID Get relative scheduled message by ID
Contacts
Contact object Create, update, or retrieve a contact Query contacts Import contacts Delete a contact Get custom contact fields Get contact by ID Update contact details Query messages sent or received by a contact Remove contact from a group Add contact to a group Query service states for a contact Query data rows for a contact Query scheduled messages for a contact Query groups for a contact Update contact field metadata
Routes
Phone object Route object Query basic routes Get basic route by ID Query custom routes Get custom route by ID Query messages for a basic route Update basic route Update custom route
Services
Service object ContactServiceState object Invoke a service Create a service Query services Get service by ID Update service configuration Get service configuration Update service details Query service logs Query contacts' states for a service Get a contact's state for a service Update a contact's state for a service Reset a contact's state for a service Delete a service
Labels
Label object Query labels Create or retrieve a label by name Get label by ID Query messages with a label Update label details Delete a label
Groups
Group object Query groups Create or retrieve a group by name Get group by ID Query contacts in a group Query scheduled messages to a group Update group details Delete a group
Data Tables
DataTable object DataRow object Create or retrieve a data table by name Get data table by ID Query rows in a data table Add new data row Update data row Delete data row Get data row by ID Get fields in data table Update field metadata Count rows by value Update table details Delete a data table Query data tables
Projects
Project object Create a project Get project by ID Query projects Get user accounts Get message statistics Update project details
Airtime Transactions
AirtimeTransaction object Query airtime transactions Get airtime transaction by ID
Organizations
Organization object Get organization by ID Query organizations Update organization settings Get billing details Get current usage Get message statistics for all projects in organization Query projects in organization
Batch Tasks
Task object Create a task Cancel a task Query tasks Get task by ID
Variable Reference
Webhook APICloud Script APIRules EngineIntegrations

REST API

Telerivet's REST API makes it easy to interact with Telerivet from your own application or website. For example, the REST API makes it easy to:

  • send SMS messages via an Android phone or SMS gateway service
  • update contact information in Telerivet (e.g. from a signup form on your own website)
  • add or remove contacts from groups
  • export your message/contact data from Telerivet into your own systems
  • schedule messages to be sent at a later time
  • control and invoke automated services

The base URL of the REST API is https://api.telerivet.com.

To explore the API in your web browser, just enter your Telerivet API key as the username (the password is ignored).

Telerivet's REST API uses predictable URLs, HTTP methods, and HTTP response codes. All responses from the REST API return JSON.

Base API Endpoint

https://api.telerivet.com

Example

The code below sends an SMS message via Telerivet:

To run the example code, you'll need to fill in variables displayed in red like YOUR_API_KEY and PROJECT_ID with the appropriate values for your account, which you can find on your API Keys page.

To change the language used for the example code, click any of the links at the top right corner of the page.

Client Libraries

If you're using one of the following programming languages, we highly recommend using one of our well-documented and supported client libraries for interacting with the REST API:

If you're using another programming language, let us know what language you're using, to help us decide which client libraries to work on next. Since Telerivet's API just uses standard HTTP methods, you can still easily integrate your application with Telerivet even without a client library.

Authentication

Authentication to the REST API occurs via HTTP Basic Auth, with your Telerivet API key as the username. To protect your API key, all API requests must be performed over SSL (i.e., HTTPS).

Alternatively, you can authenticate by passing your API key as a parameter named api_key in the URL query string or POST data. This may be easier if your development environment doesn't support Basic authentication. (However, using the api_key parameter in the URL query string is discouraged, because the API key will appear in Telerivet's server logs.)

Each API key is associated with an API client, which has certain permissions for a Telerivet project or organization. You can manage API clients and generate API keys on the Developer API settings page in the Telerivet dashboard.

Example

GET /v1 HTTP/1.1
Authorization: Basic base64_encode(YOUR_API_KEY:)
...

Request Format

For GET requests, parameters should be encoded in the query string as follows:

  • Strings and numbers as normal URL-encoded query parameters
  • Boolean true as either '1' or the case-sensitive string 'true'
  • Boolean false as either '0', or the case-sensitive string 'false'
  • Arrays recursively encoded using separate parameters for each item, like foo[0], foo[1], etc.
  • Objects recursively encoded using separate parameters for each key, like foo[bar], foo[baz], etc.

Telerivet's client libraries will automatically encode parameters in this format, which is the same as generated by the PHP http_build_query function.

For POST and PUT requests, the request body should contain either URL-encoded parameters formatted as above, or a JSON object, depending on whether the request's Content-Type header is application/x-www-form-urlencoded or application/json. JSON is recommended since it will preserve the data types of your parameters.

To reduce the amount of data transmitted in the HTTP response from Telerivet's servers to your API client, if the header Accept-Encoding: gzip is provided in the request, the response may contain a gzip-encoded response body (in which case the header Content-Encoding: gzip will be set in the response).

To reduce the amount of data transmitted in the HTTP request from your API client to Telerivet's servers, the JSON request body for POST and PUT requests may optionally be gzip-encoded, and the Content-Encoding: gzip header set in the request.

Examples

GET /v1/projects/PROJECT_ID/messages?starred=1&message_type=sms HTTP/1.1

POST /v1/projects/PROJECT_ID/messages/MESSAGE_ID HTTP/1.1
Content-Type: application/json
...

{
    "starred": true,
    "vars": {
        "foo": "bar",
        "baz": 42
    }
}

POST /v1/projects/PROJECT_ID/messages/MESSAGE_ID HTTP/1.1
Content-Type: application/x-www-form-urlencoded
...

starred=1&vars[foo]=bar&vars[baz]=42

Errors

Telerivet's REST API uses standard HTTP response codes. All successful API requests (including DELETEs) will return 200 OK. The most common response codes returned by the Telerivet API are documented at right.

In addition, the API will return a JSON response containing a property named "error" when any error is encountered (except 502 Bad Gateway). The "error" property is only present for errors, not successful responses.

Error Properties

message
string

A message describing the error

code
string

Telerivet's internal code for this error

param
string

When the code is 'invalid_param', this may contain the name of the parameter that was invalid.

HTTP Response Codes

200 OK - It worked!
400 Bad Request - A parameter was incorrect
401 Unauthorized - Your API key does not have access to the resource
402 Payment Required - Your account is unpaid or one of its limits was exceeded
404 Not Found - The URL was invalid or the requested entity did not exist
405 Method Not Allowed - The given HTTP method (e.g. GET/POST/DELETE) is not allowed for this URL
429 Too Many Requests - Your account has exceeded its API rate limit
500 Internal Server Error
502 Bad Gateway - Something went wrong on our end, try again later
503 Service Unavailable - API is temporarily offline for maintenance

Storing Custom Data

All Telerivet objects allow you to store and retrieve arbitrary data – also known as custom variables – in the 'vars' property.

For example:

  • You can use custom variables for contacts to store custom contact information, such as email addresses, alternate phone numbers, or unique IDs from another CRM system.
  • Telerivet uses custom variables for data rows to store responses and compute statistics for each of your poll questions.
  • You can use custom variables for contact/service state to track temporary information for each contact in the context of an automated conversation.

You can also store custom variables with messages, phones, projects, and more.

Each object can store up to 100 custom variables. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Setting a variable to null will delete the variable.

For certain object types (currently contacts and data rows), Telerivet also supports querying objects by their custom variables. Other types of objects cannot be queried by custom variables.

If you need to store custom data that isn't directly associated with any built-in object, Telerivet lets you define custom data tables, so you can store your data in data rows.

Example

Retrieving Objects

The Telerivet API provides three ways of retrieving objects:

Retrieving a single object by unique ID

Most objects within Telerivet can be retrieved by a GET request to a URL containing the object's unique ID. This action corresponds to client library methods like getMessageById, getContactById, getProjectById, and so on.

For these API methods, the API will return the requested object (as JSON) in the HTTP response, or a 404 error if it does not exist.

You can find the IDs for your Project(s) and Phones on the API keys page. Also, many Telerivet objects returned by the API contain IDs for other related objects.

When using the client libraries, there are often cases when you only need to call methods on an object (for example, project.sendMessage()) but you don't need to access any properties of the object (like project.name). For this this case, the client libraries provide init____ById methods that return an object but don't perform any API requests. This lets you call methods on the returned object without wasting an unnecessary API request.

Example

Retrieving a single object by a particular property, creating one if none exists

Some types of objects provide "get-or-create" API methods, which are POST requests that retrieve an object by a particular property if a matching object exists already, otherwise creating a new object.

For these API methods, the API will return the requested or newly created object (as JSON) in the HTTP response, or a 400 error if one of the parameters was invalid.

This action corresponds to client library methods like getOrCreateContact, which lets you retrieve or create a contact by name or phone number, and getOrCreateGroup, which lets you get or create a contact group by name.

Many of these API methods also support updating other properties of the object in a single API call; for example, you can get or create a contact by phone number, also updating the contact's name at the same time.

Example

Retrieving a list of objects that match a particular query

Most types of objects within Telerivet are part of collections that can be retrieved by a GET request to a particular URL.

This type of API method corresponds to client library methods like queryMessages, queryContacts, queryGroups, etc.

Since result sets may have hundreds or thousands of objects, Telerivet only returns one "page" of responses at a time. Each page contains up to 50 objects by default, which can be configured using the parameter page_size, up to a maximum of 200. The API provides two ways to retrieve multiple pages of responses:

  • By passing an offset parameter, an integer that specifies the number of objects to skip at the beginning of the result set, or
  • By passing a marker parameter, an string returned by a previous call to the same API method that specifies ID of the final object returned by that API call. This approach is more likely to be correct (i.e., return all objects exactly once without without skipping or duplicating objects) if you are iterating through a long list of objects that may also be modified concurrently.

When using Telerivet's API client libraries, all 'query' methods return an APICursor object, which provides a simple interface for iterating over multiple-page result sets, managing the marker parameter internally.

Many query methods also provide parameters to filter the result set. For more information, see the Filtering Queries section.

All query methods also accept the parameter sort_dir (either asc or desc), and some methods accept different values for the sort parameter, specifying the field by which to sort the result set. Acceptable values for the sort parameter are documented for each method in the reference below.

All query methods can also return the count of objects matching the filter in a single API request (regardless of page_size) instead of returning the actual objects themselves. When using the client libraries, simply call the count() method of the APICursor object. If using the raw API, simply add the parameter count=1. The return value will be a JSON object with a single property named count whose value is an integer.

If not using the count parameter, the API will return a JSON object with the following properties:

Result Set Properties

data
array

A list of objects matching the query

truncated
bool

This property is true if the number of results was equal to the page size, indicating that there may be additional objects in the next page of results. Even if truncated property is true, it is possible that there may not actually be any more objects on the next page.

next_marker
string

If truncated is true, this is a string that can subsequently be passed as the marker parameter to the same API method, indicating where to start the next page of results.

sort
string

The sort that was actually used for the query

sort_dir
string

The sort direction that was actually used for the query

Example

Filtering Queries

Several API methods allow you to specify filter conditions to retrieve objects matching certain criteria.

For example, the API method to query contacts accepts several parameters, including name, last_message_time, and vars.

By default, each filter parameter will only match objects containing the exact value specified (case-insensitive); e.g. name=John would match contacts whose name is "John", or "john", but not "John Smith".

Many parameters accept "modifiers" to parameter names, which lets you specify more complex filter conditions. For example, the prefix modifier will match objects where the property starts with a particular string. Modifiers are specfied by adding [modifier_name] to the end of the query parameter; e.g. name[prefix]=John .

When using one of Telerivet's client libraries, you can also express query modifiers by setting the parameter to an object with the modifier name as a property. For example, in PHP, a request with 'name' => array('prefix' => "John") is encoded exactly the same as 'name[prefix]' => "John".

When multiple filter parameters are provided, only objects matching all filters will be returned (OR queries are not currently supported).

Note that not all modifiers may be valid for every parameter; the allowed modifiers for each parameter are documented in the reference below.

Available Modifiers

prefixFilter objects where the field starts with the parameter value (case-insensitive). Only applicable for string fields.
not_prefixFilter objects where the field does not start with the parameter value (case-insensitive). Only applicable for string fields.
existsIf the parameter value is 1 or true, filter objects where the field has any (non-null) value.
If the parameter value is 0 or false, filter objects where the field does not have any value.
nullIf the parameter value is 1 or true, filter objects where the field does not have any value.
If the parameter value is 0 or false, filter objects where the field has any (non-null) value.
gteFilter objects where the value is greater than or equal to the parameter value. For string fields and custom variables the comparison is alphabetical; for numeric fields the comparison is numeric.
gtFilter objects where the field value is greater than the parameter value. For string fields and custom variables the comparison is alphabetical; for numeric fields the comparison is numeric.
ltFilter objects where the value is less than the parameter value. For string fields and custom variables the comparison is alphabetical; for numeric fields the comparison is numeric.
lteFilter objects where the value is less than or equal to the parameter value. For string fields and custom variables the comparison is alphabetical; for numeric fields the comparison is numeric.
minFilter objects where the value is greater than or equal to the parameter value (inclusive), always performing a numeric comparison. Not applicable for string fields.
maxFilter objects where the value is less than the parameter value (non-inclusive), always performing a numeric comparison. Not applicable for string fields.
neFilter objects where the field does not match the parameter value exactly (case-insensitive).
eqFilter objects where the field matches the parameter value exactly (case-insensitive). This is the same as not using any modifier.

Example

Messages

Object Type: Message

Represents a single message.

Attributes

id
string, max 34 characters

ID of the message

read-only
direction
string

Direction of the message: incoming messages are sent from one of your contacts to your phone; outgoing messages are sent from your phone to one of your contacts

Possible Values: incoming, outgoing
read-only
status
string

Current status of the message

Possible Values: ignored, processing, received, sent, queued, failed, failed_queued, cancelled, delivered, not_delivered, read
read-only
message_type
string

Type of the message

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
read-only
source
string

How the message originated within Telerivet

Possible Values: phone, provider, web, api, service, webhook, scheduled, integration
read-only
time_created
UNIX timestamp

The time that the message was created on Telerivet's servers

read-only
time_sent
UNIX timestamp

The time that the message was reported to have been sent (null for incoming messages and messages that have not yet been sent)

read-only
time_updated
UNIX timestamp

The time that the message was last updated in Telerivet.

read-only
from_number
string

The phone number that the message originated from (your number for outgoing messages, the contact's number for incoming messages)

read-only
to_number
string

The phone number that the message was sent to (your number for incoming messages, the contact's number for outgoing messages)

read-only
content
string

The text content of the message (null for USSD messages and calls)

read-only
starred
bool

Whether this message is starred in Telerivet

updatable
simulated
bool

Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)

read-only
label_ids
array of string IDs of Label

List of IDs of labels applied to this message

read-only
route_params
object

Route-specific parameters for the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when the message is sent by that type of route.

read-only
vars
object

Custom variables stored for this message. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
priority
int

Priority of this message. Telerivet will attempt to send messages with higher priority numbers first. Only defined for outgoing messages.

read-only
error_message
string

A description of the error encountered while sending a message. (This field is omitted from the API response if there is no error message.)

updatable
error_code
string

A route-specific error code encountered while sending a message. The error code values depend on the provider and may be described in the provider's API documentation. Error codes may be strings or numbers, depending on the provider. (This field is omitted from the API response if there is no error code.)

read-only
external_id
string

The ID of this message from an external SMS gateway provider (e.g. Twilio or Vonage), if available.

read-only
num_parts
number

The number of SMS parts associated with the message, if applicable and if known.

read-only
price
number

The price of this message, if known.

read-only
price_currency
string

The currency of the message price, if applicable.

read-only
duration
number

The duration of the call in seconds, if known, or -1 if the call was not answered.

read-only
ring_time
number

The length of time the call rang in seconds before being answered or hung up, if known.

read-only
audio_url
string

For voice calls, the URL of an MP3 file to play when the contact answers the call

read-only
tts_lang
string

For voice calls, the language of the text-to-speech voice

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
read-only
tts_voice
string

For voice calls, the text-to-speech voice

Possible Values: female, male
read-only
track_clicks
boolean

If true, URLs in the message content are short URLs that redirect to a destination URL.

read-only
short_urls
array

For text messages containing short URLs, this is an array of objects with the properties short_url, link_type, time_clicked (the first time that URL was clicked), and expiration_time. If link_type is "redirect", the object also contains a destination_url property. If link_type is "media", the object also contains an media_index property (the index in the media array). If link_type is "service", the object also contains a service_id property. This property is undefined for messages that do not contain short URLs.

read-only
network_code
string

A string identifying the network that sent or received the message, if known. For mobile networks, this string contains the 3-digit mobile country code (MCC) followed by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit number. For lists of mobile network operators and their corresponding MCC/MNC values, see Mobile country code Wikipedia article. The network_code property may be non-numeric for messages not sent via mobile networks.

read-only
media
array

For text messages containing media files, this is an array of objects with the properties url, type (MIME type), filename, and size (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day.

read-only
mms_parts
array

A list of parts in the MMS message (only for incoming MMS messages received via Telerivet Gateway Android app).

Each MMS part in the list is an object with the following properties:

  • cid: MMS content-id
  • type: MIME type
  • filename: original filename
  • size (int): number of bytes
  • url: URL where the content for this part is stored (secret but publicly accessible, so you could link/embed it in a web page without having to re-host it yourself)

In general, the media property of the message is recommended for retrieving information about MMS media files, instead of mms_parts. The mms_parts property is also only present when retrieving an individual MMS message by ID, not when querying a list of messages.

read-only
time_clicked
UNIX timestamp

If the message contains any short URLs, this is the first time that a short URL in the message was clicked. This property is undefined for messages that do not contain short URLs.

read-only
service_id
string ID of Service

ID of the service that handled the message (for voice calls, the service defines the call flow)

read-only
phone_id
string ID of Phone

ID of the phone (basic route) that sent or received the message

read-only
contact_id
string ID of Contact

ID of the contact that sent or received the message

read-only
route_id
string ID of Route

ID of the custom route that sent the message (if applicable)

read-only
broadcast_id
string ID of Broadcast

ID of the broadcast that this message is part of (if applicable)

read-only
scheduled_id
string ID of ScheduledMessage

ID of the scheduled message that created this message is part of (if applicable)

read-only
user_id
string, max 34 characters

ID of the Telerivet user who sent the message (if applicable)

read-only
project_id
string ID of Project

ID of the project this contact belongs to

read-only

Example

{
 "id": "SM1629708e59c5c781",
 "direction": "outgoing",
 "status": "sent",
 "message_type": "sms",
 "source": "service",
 "time_created": 1390347812,
 "time_sent": 1390347814,
 "time_updated": 1390347818,
 "from_number": "+16505550001",
 "to_number": "+16505550123",
 "content": "Thank you for registering!",
 "starred": true,
 "simulated": false,
 "label_ids": [
  "LB4f3dac27154653e0"
 ],
 "route_params": null,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "priority": 1,
 "external_id": "142092393",
 "num_parts": 1,
 "price": 0.01,
 "price_currency": "USD",
 "duration": null,
 "ring_time": null,
 "audio_url": null,
 "tts_lang": null,
 "tts_voice": null,
 "track_clicks": null,
 "short_urls": null,
 "network_code": null,
 "media": null,
 "mms_parts": null,
 "time_clicked": null,
 "service_id": "SV3d246818d0e3d1fb",
 "phone_id": "PN4d246818d0ecd1fa",
 "contact_id": "CTa1299c3d0e371023",
 "route_id": "RT2a586298d3412adf",
 "broadcast_id": "MB98918598dab29800",
 "scheduled_id": "SEa502e6f9d23f1cb6",
 "user_id": "URba3e403e98f49735",
 "project_id": "PJ2ad0100821a98bea",
 "url": "https://telerivet.com/p/asdf/message/SM1629708e59c5c781"
}

Object Type: Broadcast

Represents a collection of related outgoing messages. Typically, messages in a broadcast have the same content template and were sent at the same time; however, a broadcast can also contain messages with unrelated content and messages that were sent at different times. A broadcast is automatically created when sending a message to a group of contacts.

Attributes

id
string, max 34 characters

ID of the broadcast

read-only
recipients
array of objects

List of recipients. Each recipient is an object with a string type property, which may be "phone_number", "group", or "filter".

If the type is "phone_number", the phone_number property will be set to the recipient's phone number.

If the type is "group", the group_id property will be set to the ID of the group, and the group_name property will be set to the name of the group.

If the type is "filter", the filter_type property (string) and filter_params property (object) describe the filter used to send the broadcast. (API clients should not rely on a particular value or format of the filter_type or filter_params properties, as they may change without notice.)

read-only
title
string

Title of the broadcast. If a title was not provided when the broadcast was sent, it is automatically set to a human readable description of the first few recipients (possibly truncated)

read-only
time_created
UNIX timestamp

Time the broadcast was sent in Telerivet

read-only
last_message_time
UNIX timestamp

Time the most recent message was queued to send in this broadcast

read-only
last_send_time
UNIX timestamp

Time the most recent message was sent (or failed to send) in this broadcast, or null if no messages have been sent yet

read-only
status_counts
object

An object whose keys are the possible status codes ("queued", "sent", "failed", "failed_queued", "delivered", "not_delivered", and "cancelled"), and whose values are the number of messages in the broadcast currently in that status.

read-only
message_count
int

The total number of messages created for this broadcast. For large broadcasts, the messages may not be created immediately after the broadcast is sent. The message_count includes messages in any status, including messages that are still queued.

read-only
estimated_count
int

The estimated number of messages in this broadcast when it is complete. The estimated_count is calculated at the time the broadcast is sent. When the broadcast is completed, the estimated_count may differ from message_count if there are any blocked contacts among the recipients (blocked contacts are included in estimated_count but not in message_count), if any contacts don't have phone numbers, or if the group membership changed while the broadcast was being sent.

read-only
message_type
string

Type of message sent from this broadcast

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
read-only
content
string

The text content of the message (null for USSD messages and calls)

read-only
audio_url
string

For voice calls, the URL of an MP3 file to play when the contact answers the call

read-only
tts_lang
string

For voice calls, the language of the text-to-speech voice

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
read-only
tts_voice
string

For voice calls, the text-to-speech voice

Possible Values: female, male
read-only
replace_variables
bool

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

read-only
status
string

The current status of the broadcast.

Possible Values: queuing, sending, complete, cancelled
read-only
source
string

How the message originated within Telerivet

Possible Values: phone, provider, web, api, service, webhook, scheduled, integration
read-only
simulated
bool

Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)

read-only
track_clicks
boolean

If true, URLs in the message content will automatically be replaced with unique short URLs.

read-only
clicked_count
int

The number of messages in this broadcast containing short links that were clicked. At most one click per message is counted. If track_clicks is false, this property will be null.

read-only
label_ids
array of string IDs of Label

List of IDs of labels applied to all messages in the broadcast

read-only
media
array

For text messages containing media files, this is an array of objects with the properties url, type (MIME type), filename, and size (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day.

read-only
vars
object

Custom variables stored for this broadcast. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

read-only
route_params
object

Route-specific parameters for the messages in the broadcast. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send messages in this broadcast. The corresponding value is an object with route-specific parameters to use when sending messages with that type of route.

read-only
price
number

The total price of all messages in this broadcast, if known.

read-only
price_currency
string

The currency of the message price, if applicable.

read-only
reply_count
int

The number of replies received in response to a message sent in this broadcast. (Replies are not included in message_count ,status_counts, or price.)

read-only
last_reply_time
UNIX timestamp

Time the most recent reply was received in response to a message sent in this broadcast, or null if no replies have been sent yet

read-only
route_id
string, max 34 characters

ID of the phone or route used to send the broadcast (if applicable)

read-only
service_id
string ID of Service

The service associated with this broadcast (for voice calls, the service defines the call flow)

read-only
user_id
string, max 34 characters

ID of the Telerivet user who sent the broadcast (if applicable)

read-only
project_id
string ID of Project

ID of the project this broadcast belongs to

read-only

Example

{
 "id": "MB2489812e59c5c781",
 "recipients": [
  {
   "type": "phone_number",
   "phone_number": "+16505550123"
  },
  {
   "type": "group",
   "group_id": "CG02139128391fa",
   "group_name": "Subscribers"
  },
  {
   "type": "filter",
   "filter_type": "contacts_page",
   "filter_params": {
    "not_group": "CGc2e2dc93f4061f06",
    "vars.country": {
     "not_exists": "1"
    }
   }
  }
 ],
 "title": "+16505550123, Subscribers, Contact Filter",
 "time_created": 1390348075,
 "last_message_time": 1390348085,
 "last_send_time": 1390348086,
 "status_counts": {
  "queued": 4124,
  "sent": 1242,
  "failed": 259,
  "failed_queued": 0,
  "delivered": 2492,
  "not_delivered": 241,
  "cancelled": 0
 },
 "message_count": 8358,
 "estimated_count": 12942,
 "message_type": "sms",
 "content": "Hello [[contact.name]]!",
 "audio_url": null,
 "tts_lang": null,
 "tts_voice": null,
 "replace_variables": true,
 "status": "queuing",
 "source": "service",
 "simulated": false,
 "track_clicks": null,
 "clicked_count": 12,
 "label_ids": [
  "LB4f3dac27154653e0"
 ],
 "media": null,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "route_params": null,
 "price": 13.34,
 "price_currency": "USD",
 "reply_count": 43,
 "last_reply_time": 1390348132,
 "route_id": "RT2a586298d3412adf",
 "service_id": "SV3d246818d0e3d1fb",
 "user_id": "URba3e403e98f49735",
 "project_id": "PJ2ad0100821a98bea"
}

Send a message

POST /v1/projects/<project_id>/messages/send

Sends one message (SMS, MMS, chat app message, voice call, or USSD request).

For a complete example (in PHP) of how to use the Telerivet API to send SMS from a form on your website, see send_api_example.php

Arguments

message_type
string, optional

Type of message to send. If text, will use the default text message type for the selected route.

Possible Values: text, sms, mms, ussd, call, chat, service
Default: text
content
string, required if sending SMS message

Content of the message to send (if message_type is call, the text will be spoken during a text-to-speech call)

to_number
string, required if contact_id not set

Phone number to send the message to

contact_id
string ID of Contact, required if to_number not set

ID of the contact to send the message to

route_id
string, optional

ID of the phone or route to send the message from

Default: default sender route ID for your project
status_url
string, optional

Webhook callback URL to be notified when message status changes

status_secret
string, optional

POST parameter 'secret' passed to status_url

replace_variables
bool, optional

Set to true to evaluate variables like [[contact.name]] in message content. (See available variables) (is_template parameter also accepted)

Default: false
track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs.

Default: false
short_link_params
object, optional

If track_clicks is true, short_link_params may be used to specify custom parameters for each short link in the message. The following parameters are supported:

domain (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.

expiration_sec (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.

media_urls
array, optional

URLs of media files to attach to the text message. If message_type is sms, short links to each URL will be appended to the end of the content (separated by a new line).

By default, each file must have a https:// or http:// URL, which requires the file to be uploaded somewhere that is accessible via the internet. For media files that are not already accessible via the internet, the media_urls parameter also supports data URIs with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum file size of 2 MB. To send media via data URIs, contact Telerivet to request enabling the data URIs feature for your project.

route_params
object, optional

Route-specific parameters for the message. The parameters object should have one or more keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value should be an object with route-specific parameters to use if the message is sent by that type of route.

label_ids
array of string IDs of Label, optional

List of IDs of labels to add to this message

vars
object, optional

Custom variables to store with the message

priority
int, optional

Priority of the message. Telerivet will attempt to send messages with higher priority numbers first (for example, so you can prioritize an auto-reply ahead of a bulk message to a large group).

Possible Values: 1, 2
Default: 1
simulated
bool, optional

Set to true to test the Telerivet API without actually sending a message from the route

Default: false
service_id
string ID of Service, optional

Service that defines the call flow of the voice call (when message_type is call)

audio_url
string, optional

The URL of an MP3 file to play when the contact answers the call (when message_type is call).

If audio_url is provided, the text-to-speech voice is not used to say content, although you can optionally use content to indicate the script for the audio.

For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line.

tts_lang
string, optional

The language of the text-to-speech voice (when message_type is call)

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
Default: en-US
tts_voice
string, optional

The name of the text-to-speech voice (when message_type=call)

Possible Values: female, male
Default: female

Return Type

Message

Permission Required

Send messages

Example

Send a message to a group

POST /v1/projects/<project_id>/send_broadcast

Sends a text message (optionally with mail-merge templates) or voice call to a group or a list of up to 500 phone numbers.

With message_type=service, invokes an automated service (such as a poll) for a group or list of phone numbers. Any service that can be triggered for a contact can be invoked via this method, whether or not the service actually sends a message.

Arguments

message_type
string, optional

Type of message to send. If text, will use the default text message type for the selected route.

Possible Values: text, sms, mms, call, chat, service
Default: text
content
string, required if sending SMS message

Content of the message to send

group_id
string ID of Group, required if to_numbers not set

ID of the group to send the message to

to_numbers
array of strings, required if group_id not set

List of up to 500 phone numbers to send the message to

route_id
string ID of Phone, optional

ID of the phone or route to send the message from

Default: default sender route ID
title
string, optional

Title of the broadcast. If a title is not provided, a title will automatically be generated from the recipient group name or phone numbers.

status_url
string, optional

Webhook callback URL to be notified when message status changes

status_secret
string, optional

POST parameter 'secret' passed to status_url

label_ids
array of string IDs of Label, optional

Array of IDs of labels to add to all messages sent (maximum 5). Does not apply when message_type=service, since the labels are determined by the service itself.

exclude_contact_id
string, optional

Optionally excludes one contact from receiving the message (only when group_id is set)

replace_variables
bool, optional

Set to true to evaluate variables like [[contact.name]] in message content (See available variables) (is_template parameter also accepted)

Default: false
track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs.

Default: false
short_link_params
object, optional

If track_clicks is true, short_link_params may be used to specify custom parameters for each short link in the message. The following parameters are supported:

domain (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.

expiration_sec (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.

media_urls
array, optional

URLs of media files to attach to the text message. If message_type is sms, short links to each URL will be appended to the end of the content (separated by a new line).

By default, each file must have a https:// or http:// URL, which requires the file to be uploaded somewhere that is accessible via the internet. For media files that are not already accessible via the internet, the media_urls parameter also supports data URIs with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum file size of 2 MB. To send media via data URIs, contact Telerivet to request enabling the data URIs feature for your project.

vars
object, optional

Custom variables to set for each message

route_params
object, optional

Route-specific parameters for the messages in the broadcast. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send messages in this broadcast. The corresponding value is an object with route-specific parameters to use when sending messages with that type of route.

service_id
string ID of Service, required if message_type is service

Service to invoke for each recipient (when message_type is call or service)

audio_url
string, optional

The URL of an MP3 file to play when the contact answers the call (when message_type is call).

If audio_url is provided, the text-to-speech voice is not used to say content, although you can optionally use content to indicate the script for the audio.

For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line.

tts_lang
string, optional

The language of the text-to-speech voice (when message_type is call)

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
Default: en-US
tts_voice
string, optional

The name of the text-to-speech voice (when message_type=call)

Possible Values: female, male
Default: female

Return Type

Broadcast

Permission Required

Send messages

Example

Send multiple messages

POST /v1/projects/<project_id>/send_multi

Sends up to 100 different messages in a single API request. This method is significantly faster than sending a separate API request for each message.

Arguments

messages
array, required

Array of up to 100 objects with content and to_number properties. Each object may also contain the optional properties status_url, status_secret, vars, and/or priority, which override the parameters of the same name defined below, to allow passing different values for each message.

message_type
string, optional

Type of message to send. If text, will use the default text message type for the selected route.

Possible Values: text, sms, mms, call, chat, service
Default: text
route_id
string ID of Phone, optional

ID of the phone or route to send the messages from

Default: default sender route ID
broadcast_id
string ID of Broadcast, optional

ID of an existing broadcast to associate the messages with

broadcast_title
string, optional

Title of broadcast to create (when broadcast_id is not provided). When sending more than 100 messages over multiple API requests, you can associate all messages with the same broadcast by providing a broadcast_title parameter in the first API request, then retrieving the broadcast_id property from the API response, and passing it as the broadcast_id parameter in subsequent API requests.

status_url
string, optional

Webhook callback URL to be notified when message status changes

status_secret
string, optional

POST parameter 'secret' passed to status_url

label_ids
array of string IDs of Label, optional

Array of IDs of labels to add to each message (maximum 5)

replace_variables
bool, optional

Set to true to evaluate variables like [[contact.name]] in message content (See available variables) (is_template parameter also accepted)

Default: false
track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs.

Default: false
short_link_params
object, optional

If track_clicks is true, short_link_params may be used to specify custom parameters for each short link in the message. The following parameters are supported:

domain (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.

expiration_sec (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.

media_urls
array, optional

URLs of media files to attach to the text message. If message_type is sms, short links to each URL will be appended to the end of the content (separated by a new line).

By default, each file must have a https:// or http:// URL, which requires the file to be uploaded somewhere that is accessible via the internet. For media files that are not already accessible via the internet, the media_urls parameter also supports data URIs with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum file size of 2 MB. To send media via data URIs, contact Telerivet to request enabling the data URIs feature for your project.

route_params
object, optional

Route-specific parameters to apply to all messages. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send messages. The corresponding value is an object with route-specific parameters to use when sending messages with that type of route.

vars
object, optional

Custom variables to store with the message

priority
int, optional

Priority of the message. Telerivet will attempt to send messages with higher priority numbers first (for example, so you can prioritize an auto-reply ahead of a bulk message to a large group).

Possible Values: 1, 2
Default: 1
simulated
bool, optional

Set to true to test the Telerivet API without actually sending a message from the route

Default: false

Return Type

object

Return Value Properties

messages
array

List of objects representing each newly created message, with the same length and order as provided in the messages parameter in the API request. Each object has the id and status properties, and may have the property error_message. (Other properties of the Message object are omitted in order to reduce the amount of redundant data sent in each API response.) If the messages parameter in the API request contains items with to_number values that are associated with blocked contacts, the id and status properties corresponding to those items will be null, and no messages will be sent to those numbers.

broadcast_id
string

ID of broadcast that these messages are associated with, if broadcast_id or broadcast_title parameter is provided in the API request.

Permission Required

Send messages

Example

Query messages

GET /v1/projects/<project_id>/messages

Queries messages within the given project.

Note: To be notified of new incoming messages as they are received, use the Webhook API.

Arguments

label_id
string ID of Label, optional

Filter messages with a label

direction
string, optional

Filter messages by direction

Possible Values: incoming, outgoing
message_type
string, optional

Filter messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
source
string, optional

Filter messages by source

Possible Values: phone, provider, web, api, service, webhook, scheduled, integration
starred
bool, optional

Filter messages by starred/unstarred

status
string, optional

Filter messages by status

Possible Values: ignored, processing, received, sent, queued, failed, failed_queued, cancelled, delivered, not_delivered, read
time_created[min]
UNIX timestamp, optional

Filter messages created on or after a particular time

time_created[max]
UNIX timestamp, optional

Filter messages created before a particular time

external_id
string, optional

Filter messages by ID from an external provider

Allowed Modifiers: external_id[ne], external_id[exists] (?)
contact_id
string ID of Contact, optional

ID of the contact who sent/received the message

Allowed Modifiers: contact_id[ne], contact_id[exists] (?)
phone_id
string ID of Phone, optional

ID of the phone (basic route) that sent/received the message

broadcast_id
string ID of Broadcast, optional

ID of the broadcast containing the message

Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?)
scheduled_id
string ID of ScheduledMessage, optional

ID of the scheduled message that created this message

Allowed Modifiers: scheduled_id[ne], scheduled_id[exists] (?)
group_id
string ID of Group, optional

Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group.

sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Message

Raw API: Query result of Message

Permission Required

View messages

Example

Remove a label from a message

DELETE /v1/projects/<project_id>/labels/<label_id>/messages/<message_id>

Removes a label from the given message.

Arguments

None

Return Type

undefined

Permission Required

Send messages

Example

Add an incoming message

POST /v1/projects/<project_id>/messages/receive

Add an incoming message to Telerivet. Acts the same as if the message was received by a phone. Also triggers any automated services that apply to the message.

Arguments

content
string, required unless `message_type` is `call`

Content of the incoming message

message_type
string, optional

Type of message

Possible Values: sms, call, chat
Default: sms
from_number
string, required

Phone number that sent the incoming message

phone_id
string ID of Phone, required

ID of the phone (basic route) that received the message

to_number
string, optional

Phone number that the incoming message was sent to

Default: phone number of the phone that received the message
simulated
bool, optional

If true, Telerivet will not send automated replies to actual phones

starred
bool, optional

True if this message should be starred

label_ids
array of string IDs of Label, optional

Array of IDs of labels to add to this message (maximum 5)

vars
object, optional

Custom variables to set for this message

Return Type

Message

Permission Required

Send messages

Example

Get custom message fields

GET /v1/projects/<project_id>/message_fields

Gets a list of all custom fields defined for messages in this project. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and 'lookup_key'. (Fields are automatically created any time a Contact's 'vars' property is updated.)

Arguments

None

Return Type

array

Permission Required

View messages

Example

Get broadcast by ID

GET /v1/projects/<project_id>/broadcasts/<broadcast_id>

Retrieves the broadcast with the given ID.

Arguments

None

Return Type

Broadcast

Permission Required

View messages

Example

Query broadcasts

GET /v1/projects/<project_id>/broadcasts

Queries broadcasts within the given project.

Note: To be notified of new broadcasts as they are sent, use the Webhook API.

Arguments

time_created[min]
UNIX timestamp, optional

Filter broadcasts created on or after a particular time

time_created[max]
UNIX timestamp, optional

Filter broadcasts created before a particular time

last_message_time[min]
UNIX timestamp, optional

Filter broadcasts with most recent message on or after a particular time

last_message_time[max]
UNIX timestamp, optional

Filter broadcasts with most recent message before a particular time

sort
string, optional

Sort the results based on a field

Possible Values: default, last_message_time
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Broadcast

Raw API: Query result of Broadcast

Permission Required

View messages

Example

Get message by ID

GET /v1/projects/<project_id>/messages/<message_id>

Retrieves the message with the given ID.

Arguments

None

Return Type

Message

Permission Required

View messages

Example

Add a label to a message

PUT /v1/projects/<project_id>/labels/<label_id>/messages/<message_id>

Adds a label to the given message.

Arguments

None

Return Type

undefined

Permission Required

Send messages

Example

Cancel sending a broadcast

POST /v1/projects/<project_id>/broadcasts/<broadcast_id>/cancel

Cancels sending a broadcast that has not yet been completely sent. No additional messages will be queued, and any existing queued messages will be cancelled when they would otherwise have been sent (except for messages already queued on the Telerivet Android app, which will not be automatically cancelled).

Arguments

None

Return Type

Broadcast

Permission Required

Send messages

Example

Delete a message

DELETE /v1/projects/<project_id>/messages/<message_id>

Deletes this message.

Arguments

None

Return Type

undefined

Permission Required

Delete messages

Example

Cancel sending a message

POST /v1/projects/<project_id>/messages/<message_id>/cancel

Cancels sending a message that has not yet been sent. Returns the updated message object. Only valid for outgoing messages that are currently in the queued, retrying, or cancelled states. For other messages, the API will return an error with the code 'not_cancellable'.

Arguments

None

Return Type

Message

Permission Required

Send messages

Example

Resend a message

POST /v1/projects/<project_id>/messages/<message_id>/resend

Resends a message, for example if the message failed to send or if it was not delivered. If the message was originally in the queued, retrying, failed, or cancelled states, then Telerivet will return the same message object. Otherwise, Telerivet will create and return a new message object.

Arguments

route_id
string, optional

ID of the phone or route to send the message from

Return Type

Message

Permission Required

Send messages

Example

Update message details

POST /v1/projects/<project_id>/messages/<message_id>

Updates writable fields on the given message

Arguments

starred
bool, optional

Whether this message is starred in Telerivet

vars
object, optional

Custom variables stored for this message. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

error_message
string, optional

A description of the error encountered while sending a message. (This field is omitted from the API response if there is no error message.)

Return Type

Client libraries: undefined

Raw API: Message

Permission Required

Send messages

Example

Update message field metadata

POST /v1/projects/<project_id>/message_fields/<variable>

Allows customizing how a custom message field is displayed in the Telerivet web app.

The variable path parameter can contain the characters a-z, A-Z, 0-9, and _, and may be up to 32 characters in length.

Arguments

name
string, max 64 characters, optional

Display name for the field

type
string, optional

Field type

Possible Values: text, long_text, secret, phone_number, email, url, audio, date, date_time, number, boolean, checkbox, select, radio, route
order
int, optional

Order in which to display the field

items
array, required if type is `select`

Array of up to 100 objects containing value and label string properties to show in the dropdown list when type is select. Each value and label must be between 1 and 256 characters in length.

hide_values
bool, optional

Set to true to avoid showing values of this field on the Messages page

Return Type

object

Permission Required

Send messages

Example

Scheduled Messages

Object Type: ScheduledMessage

Represents a scheduled message within Telerivet.

Attributes

id
string, max 34 characters

ID of the scheduled message

read-only
content
string

Text content of the scheduled message

updatable
rrule
string

Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445.

updatable
timezone_id
string

Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article.

updatable
recipients
array of objects

List of recipients. Each recipient is an object with a string type property, which may be "phone_number", "group", or "filter".

If the type is "phone_number", the phone_number property will be set to the recipient's phone number.

If the type is "group", the group_id property will be set to the ID of the group, and the group_name property will be set to the name of the group.

If the type is "filter", the filter_type property (string) and filter_params property (object) describe the filter used to send the broadcast. (API clients should not rely on a particular value or format of the filter_type or filter_params properties, as they may change without notice.)

read-only
recipients_str
string

A string with a human readable description of the first few recipients (possibly truncated)

read-only
group_id
string ID of Group

ID of the group to send the message to (null if the recipient is an individual contact, or if there are multiple recipients)

updatable
contact_id
string ID of Contact

ID of the contact to send the message to (null if the recipient is a group, or if there are multiple recipients)

updatable
to_number
string

Phone number to send the message to (null if the recipient is a group, or if there are multiple recipients)

updatable
route_id
string

ID of the phone or route the message will be sent from

updatable
service_id
string ID of Service

The service associated with this message (for voice calls, the service defines the call flow)

updatable
audio_url
string

For voice calls, the URL of an MP3 file to play when the contact answers the call

updatable
tts_lang
string

For voice calls, the language of the text-to-speech voice

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
updatable
tts_voice
string

For voice calls, the text-to-speech voice

Possible Values: female, male
updatable
message_type
string

Type of scheduled message

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
read-only
time_created
UNIX timestamp

Time the scheduled message was created in Telerivet

read-only
start_time
UNIX timestamp

The time that the message will be sent (or first sent for recurring messages)

updatable
end_time
UNIX timestamp

Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)

updatable
prev_time
UNIX timestamp

The most recent time that Telerivet has sent this scheduled message (null if it has never been sent)

read-only
next_time
UNIX timestamp

The next upcoming time that Telerivet will sent this scheduled message (null if it will not be sent again)

read-only
occurrences
int

Number of times this scheduled message has already been sent

read-only
replace_variables
bool

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

updatable
track_clicks
boolean

If true, URLs in the message content will automatically be replaced with unique short URLs

updatable
media
array

For text messages containing media files, this is an array of objects with the properties url, type (MIME type), filename, and size (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day.

read-only
route_params
object

Route-specific parameters to use when sending the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when sending a message with that type of route.

updatable
vars
object

Custom variables stored for this scheduled message (copied to Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
label_ids
array of string IDs of Label

IDs of labels to add to the Message

updatable
relative_scheduled_id
string

ID of the relative scheduled message this scheduled message was created from, if applicable

read-only
project_id
string

ID of the project this scheduled message belongs to

read-only

Example

{
 "id": "SEfaf2411ed3584f08",
 "content": "hello world!",
 "rrule": "COUNT=1",
 "timezone_id": "America/Los_Angeles",
 "recipients": [
  {
   "type": "phone_number",
   "phone_number": "+16505550123"
  },
  {
   "type": "group",
   "group_id": "CG02139128391fa",
   "group_name": "Subscribers"
  }
 ],
 "recipients_str": "+16505550123, Subscribers",
 "group_id": null,
 "contact_id": null,
 "to_number": null,
 "route_id": "PN4d246818d0ecd1fa",
 "service_id": "SV3d246818d0e3d1fb",
 "audio_url": null,
 "tts_lang": null,
 "tts_voice": null,
 "message_type": "sms",
 "time_created": 1395617416,
 "start_time": 1395617516,
 "end_time": null,
 "prev_time": null,
 "next_time": 1395617516,
 "occurrences": 0,
 "replace_variables": false,
 "track_clicks": null,
 "media": null,
 "route_params": null,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "label_ids": [
  "LB4f3dac27154653e0"
 ],
 "relative_scheduled_id": "PJ2ad0100821a98bea",
 "project_id": "PJ2ad0100821a98bea"
}

Object Type: RelativeScheduledMessage

A relative scheduled message is a message that is scheduled relative to a date stored as a custom field for each recipient contact. This allows scheduling messages on a different date for each contact, for example on their birthday, a certain number of days before an appointment, or a certain number of days after enrolling in a campaign.

Telerivet will automatically create a ScheduledMessage for each contact matching a RelativeScheduledMessage.

Any service that can be manually triggered for a contact (including polls) may also be scheduled via a relative scheduled message, whether or not the service actually sends a message.

Attributes

id
string, max 34 characters

ID of the relative scheduled message

read-only
content
string

Text content of the relative scheduled message

updatable
time_of_day
string

Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23)

updatable
date_variable
string

Custom contact variable storing date or date/time values relative to which messages will be scheduled.

updatable
offset_scale
string

The type of interval (day/week/month/year) that will be used to adjust the scheduled date relative to the date stored in the contact's date_variable, when offset_count is non-zero (D=day, W=week, M=month, Y=year)

Possible Values: D, W, M, Y
updatable
offset_count
int

The number of days/weeks/months/years to adjust the date of the scheduled message relative relative to the date stored in the contact's date_variable. May be positive, negative, or zero.

updatable
rrule
string

Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445.

updatable
end_time
UNIX timestamp

Time after which recurring messages will stop (not applicable to non-recurring scheduled messages)

updatable
timezone_id
string

Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article.

updatable
recipients_str
string

A string with a human readable description of the recipient

read-only
group_id
string ID of Group

ID of the group to send the message to (null if the recipient is an individual contact)

updatable
contact_id
string ID of Contact

ID of the contact to send the message to (null if the recipient is a group)

updatable
to_number
string

Phone number to send the message to (null if the recipient is a group)

updatable
route_id
string

ID of the phone or route the message will be sent from

updatable
service_id
string ID of Service

The service associated with this message (for voice calls, the service defines the call flow)

updatable
audio_url
string

For voice calls, the URL of an MP3 file to play when the contact answers the call

updatable
tts_lang
string

For voice calls, the language of the text-to-speech voice

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
updatable
tts_voice
string

For voice calls, the text-to-speech voice

Possible Values: female, male
updatable
message_type
string

Type of scheduled message

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
read-only
time_created
UNIX timestamp

Time the relative scheduled message was created in Telerivet

read-only
replace_variables
bool

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

updatable
track_clicks
boolean

If true, URLs in the message content will automatically be replaced with unique short URLs

updatable
media
array

For text messages containing media files, this is an array of objects with the properties url, type (MIME type), filename, and size (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day.

read-only
route_params
object

Route-specific parameters to use when sending the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when sending a message with that type of route.

updatable
vars
object

Custom variables stored for this scheduled message (copied to each ScheduledMessage and Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
label_ids
array of string IDs of Label

IDs of labels to add to the Message

updatable
project_id
string

ID of the project this relative scheduled message belongs to

read-only

Example

{
 "id": "SEfaf2411ed3584f08",
 "content": "hello world!",
 "time_of_day": "15:07",
 "date_variable": "date",
 "offset_scale": "D",
 "offset_count": 3,
 "rrule": "COUNT=1",
 "end_time": null,
 "timezone_id": "America/Los_Angeles",
 "recipients_str": "Subscribers",
 "group_id": null,
 "contact_id": null,
 "to_number": null,
 "route_id": "PN4d246818d0ecd1fa",
 "service_id": "SV3d246818d0e3d1fb",
 "audio_url": null,
 "tts_lang": null,
 "tts_voice": null,
 "message_type": "sms",
 "time_created": 1395617416,
 "replace_variables": false,
 "track_clicks": null,
 "media": null,
 "route_params": null,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "label_ids": [
  "LB4f3dac27154653e0"
 ],
 "project_id": "PJ2ad0100821a98bea"
}

Schedule a message

POST /v1/projects/<project_id>/scheduled

Schedules a message to a group or single contact. Note that Telerivet only sends scheduled messages approximately once every 15 seconds, so it is not possible to control the exact second at which a scheduled message is sent.

Only one of the parameters group_id, to_number, and contact_id should be provided.

With message_type=service, schedules an automated service (such as a poll) to be invoked for a group or list of phone numbers. Any service that can be triggered for a contact can be scheduled via this method, whether or not the service actually sends a message.

Arguments

message_type
string, optional

Type of message to send

Possible Values: text, sms, mms, ussd, call, chat, service
Default: text
content
string, required if sending text message

Content of the message to schedule

group_id
string ID of Group, optional

ID of the group to send the message to

to_number
string, optional

Phone number to send the message to

contact_id
string ID of Contact, optional

ID of the contact to send the message to

start_time
UNIX timestamp, required if start_time_offset not set

The time that the message will be sent (or first sent for recurring messages)

start_time_offset
int, required if start_time not set

Number of seconds from now until the message is sent

rrule
string, optional

A recurrence rule describing the how the schedule repeats, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see https://tools.ietf.org/html/rfc2445#section-4.3.10. (UNTIL is ignored; use end_time parameter instead).

Default: COUNT=1 (one-time scheduled message, does not repeat)
route_id
string ID of Phone, optional

ID of the phone or route to send the message from

Default: default sender route ID
service_id
string ID of Service, required if message_type is service

Service to invoke for each recipient (when message_type is call or service)

audio_url
string, optional

The URL of an MP3 file to play when the contact answers the call (when message_type is call).

If audio_url is provided, the text-to-speech voice is not used to say content, although you can optionally use content to indicate the script for the audio.

For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line.

tts_lang
string, optional

The language of the text-to-speech voice (when message_type is call)

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
Default: en-US
tts_voice
string, optional

The name of the text-to-speech voice (when message_type=call)

Possible Values: female, male
Default: female
track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs.

Default: false
short_link_params
object, optional

If track_clicks is true, short_link_params may be used to specify custom parameters for each short link in the message. The following parameters are supported:

domain (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.

expiration_sec (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.

replace_variables
bool, optional

Set to true to evaluate variables like [[contact.name]] in message content (is_template parameter also accepted)

Default: false
media_urls
array, optional

URLs of media files to attach to the text message. If message_type is sms, short links to each URL will be appended to the end of the content (separated by a new line).

By default, each file must have a https:// or http:// URL, which requires the file to be uploaded somewhere that is accessible via the internet. For media files that are not already accessible via the internet, the media_urls parameter also supports data URIs with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum file size of 2 MB. To send media via data URIs, contact Telerivet to request enabling the data URIs feature for your project.

route_params
object, optional

Route-specific parameters to use when sending the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when sending a message with that type of route.

label_ids
array of string IDs of Label, optional

Array of IDs of labels to add to the sent messages (maximum 5). Does not apply when message_type=service, since the labels are determined by the service itself.

timezone_id
string, optional

TZ database timezone ID; see List of tz database time zones Wikipedia article.

Default: project default timezone
end_time
UNIX timestamp, optional

Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)

end_time_offset
int, optional

Number of seconds from now until the recurring message will stop

vars
object, optional

Custom variables to set for this scheduled message, which will be copied to each message sent from this scheduled message

Return Type

ScheduledMessage

Permission Required

Send messages

Example

Query scheduled messages

GET /v1/projects/<project_id>/scheduled

Queries scheduled messages within the given project.

Arguments

message_type
string, optional

Filter scheduled messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
time_created
UNIX timestamp, optional

Filter scheduled messages by time_created

Allowed Modifiers: time_created[min], time_created[max] (?)
next_time
UNIX timestamp, optional

Filter scheduled messages by next_time

Allowed Modifiers: next_time[min], next_time[max], next_time[exists] (?)
relative_scheduled_id
string ID of RelativeScheduledMessage, optional

Filter scheduled messages created for a relative scheduled message

sort
string, optional

Sort the results based on a field

Possible Values: default, next_time
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of ScheduledMessage

Raw API: Query result of ScheduledMessage

Permission Required

View messages

Example

Update scheduled message

POST /v1/projects/<project_id>/scheduled/<scheduled_msg_id>

Updates writable fields on the given scheduled message.

Arguments

content
string, optional

Text content of the scheduled message

rrule
string, optional

Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445.

timezone_id
string, optional

Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article.

group_id
string ID of Group, optional

ID of the group to send the message to (null if the recipient is an individual contact, or if there are multiple recipients)

contact_id
string ID of Contact, optional

ID of the contact to send the message to (null if the recipient is a group, or if there are multiple recipients)

to_number
string, optional

Phone number to send the message to (null if the recipient is a group, or if there are multiple recipients)

route_id
string, optional

ID of the phone or route the message will be sent from

service_id
string ID of Service, optional

The service associated with this message (for voice calls, the service defines the call flow)

audio_url
string, optional

For voice calls, the URL of an MP3 file to play when the contact answers the call

tts_lang
string, optional

For voice calls, the language of the text-to-speech voice

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
tts_voice
string, optional

For voice calls, the text-to-speech voice

Possible Values: female, male
start_time
UNIX timestamp, optional

The time that the message will be sent (or first sent for recurring messages)

end_time
UNIX timestamp, optional

Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)

replace_variables
bool, optional

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs

route_params
object, optional

Route-specific parameters to use when sending the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when sending a message with that type of route.

vars
object, optional

Custom variables stored for this scheduled message (copied to Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

label_ids
array of string IDs of Label, optional

IDs of labels to add to the Message

Return Type

Client libraries: undefined

Raw API: ScheduledMessage

Permission Required

Send messages

Example

Cancel a scheduled message

DELETE /v1/projects/<project_id>/scheduled/<scheduled_msg_id>

Cancels this scheduled message.

Arguments

None

Return Type

undefined

Permission Required

Send messages

Example

Create relative scheduled message

POST /v1/projects/<project_id>/relative_scheduled

Creates a relative scheduled message. This allows scheduling messages on a different date for each contact, for example on their birthday, a certain number of days before an appointment, or a certain number of days after enrolling in a campaign.

Telerivet will automatically create a ScheduledMessage for each contact matching a RelativeScheduledMessage.

Relative scheduled messages can be created for a group or an individual contact, although dynamic groups are not supported. Only one of the parameters group_id, to_number, and contact_id should be provided.

With message_type=service, schedules an automated service (such as a poll). Any service that can be triggered for a contact can be scheduled via this method, whether or not the service actually sends a message.

Arguments

message_type
string, optional

Type of message to send

Possible Values: text, sms, mms, call, chat, service
Default: text
content
string, required if sending text message

Content of the message to schedule

group_id
string ID of Group, optional

ID of the group to send the message to. Dynamic groups are not supported.

to_number
string, optional

Phone number to send the message to

contact_id
string ID of Contact, optional

ID of the contact to send the message to

time_of_day
string, required

Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23)

timezone_id
string, optional

TZ database timezone ID; see List of tz database time zones Wikipedia article.

Default: project default timezone
date_variable
string, required

Custom contact variable storing date or date/time values relative to which messages will be scheduled.

offset_scale
string, optional

The type of interval (day/week/month/year) that will be used to adjust the scheduled date relative to the date stored in the contact's date_variable, when offset_count is non-zero (D=day, W=week, M=month, Y=year)

Possible Values: D, W, M, Y
Default: D
offset_count
int, optional

The number of days/weeks/months/years to adjust the date of the scheduled message relative relative to the date stored in the custom contact variable identified by the date_variable parameter. May be positive, negative, or zero.

Default: 0
rrule
string, optional

A recurrence rule describing the how the schedule repeats, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see https://tools.ietf.org/html/rfc2445#section-4.3.10. (UNTIL is ignored; use end_time parameter instead).

Default: COUNT=1 (one-time scheduled message, does not repeat)
route_id
string ID of Phone, optional

ID of the phone or route to send the message from

Default: default sender route ID
service_id
string ID of Service, required if message_type is service

Service to invoke for each recipient (when message_type is call or service)

audio_url
string, optional

The URL of an MP3 file to play when the contact answers the call (when message_type is call).

If audio_url is provided, the text-to-speech voice is not used to say content, although you can optionally use content to indicate the script for the audio.

For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line.

tts_lang
string, optional

The language of the text-to-speech voice (when message_type is call)

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
Default: en-US
tts_voice
string, optional

The name of the text-to-speech voice (when message_type=call)

Possible Values: female, male
Default: female
track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs.

Default: false
short_link_params
object, optional

If track_clicks is true, short_link_params may be used to specify custom parameters for each short link in the message. The following parameters are supported:

domain (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.

expiration_sec (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL. If null, the short links will not expire.

replace_variables
bool, optional

Set to true to evaluate variables like [[contact.name]] in message content

Default: false
media_urls
array, optional

URLs of media files to attach to the text message. If message_type is sms, short links to each URL will be appended to the end of the content (separated by a new line).

By default, each file must have a https:// or http:// URL, which requires the file to be uploaded somewhere that is accessible via the internet. For media files that are not already accessible via the internet, the media_urls parameter also supports data URIs with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum file size of 2 MB. To send media via data URIs, contact Telerivet to request enabling the data URIs feature for your project.

route_params
object, optional

Route-specific parameters to use when sending the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when sending a message with that type of route.

label_ids
array of string IDs of Label, optional

Array of IDs of labels to add to the sent messages (maximum 5). Does not apply when message_type=service, since the labels are determined by the service itself.

end_time
UNIX timestamp, optional

Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)

end_time_offset
int, optional

Number of seconds from now until the recurring message will stop

vars
object, optional

Custom variables to set for this relative scheduled message, which will be copied to each message sent from this scheduled message

Return Type

RelativeScheduledMessage

Permission Required

Send messages

Example

Query relative scheduled messages

GET /v1/projects/<project_id>/relative_scheduled

Queries relative scheduled messages within the given project.

Arguments

message_type
string, optional

Filter relative scheduled messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
time_created
UNIX timestamp, optional

Filter relative scheduled messages by time_created

Allowed Modifiers: time_created[min], time_created[max] (?)
group_id
string ID of Group, optional

Filter relative scheduled messages sent to a group

contact_id
string ID of Contact, optional

Filter relative scheduled messages sent to an individual contact

sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of RelativeScheduledMessage

Raw API: Query result of RelativeScheduledMessage

Permission Required

View messages

Example

Update relative scheduled message

POST /v1/projects/<project_id>/relative_scheduled/<rel_scheduled_msg_id>

Updates writable fields on the given relative scheduled message.

Arguments

content
string, optional

Text content of the relative scheduled message

time_of_day
string, optional

Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23)

date_variable
string, optional

Custom contact variable storing date or date/time values relative to which messages will be scheduled.

offset_scale
string, optional

The type of interval (day/week/month/year) that will be used to adjust the scheduled date relative to the date stored in the contact's date_variable, when offset_count is non-zero (D=day, W=week, M=month, Y=year)

Possible Values: D, W, M, Y
offset_count
int, optional

The number of days/weeks/months/years to adjust the date of the scheduled message relative relative to the date stored in the contact's date_variable. May be positive, negative, or zero.

rrule
string, optional

Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445.

end_time
UNIX timestamp, optional

Time after which recurring messages will stop (not applicable to non-recurring scheduled messages)

timezone_id
string, optional

Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article.

group_id
string ID of Group, optional

ID of the group to send the message to (null if the recipient is an individual contact)

contact_id
string ID of Contact, optional

ID of the contact to send the message to (null if the recipient is a group)

to_number
string, optional

Phone number to send the message to (null if the recipient is a group)

route_id
string, optional

ID of the phone or route the message will be sent from

service_id
string ID of Service, optional

The service associated with this message (for voice calls, the service defines the call flow)

audio_url
string, optional

For voice calls, the URL of an MP3 file to play when the contact answers the call

tts_lang
string, optional

For voice calls, the language of the text-to-speech voice

Possible Values: en-US, en-GB, en-GB-WLS, en-AU, en-IN, da-DK, nl-NL, fr-FR, fr-CA, de-DE, is-IS, it-IT, pl-PL, pt-BR, pt-PT, ru-RU, es-ES, es-US, sv-SE
tts_voice
string, optional

For voice calls, the text-to-speech voice

Possible Values: female, male
replace_variables
bool, optional

Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise

track_clicks
boolean, optional

If true, URLs in the message content will automatically be replaced with unique short URLs

route_params
object, optional

Route-specific parameters to use when sending the message. The parameters object may have keys matching the phone_type field of a phone (basic route) that may be used to send the message. The corresponding value is an object with route-specific parameters to use when sending a message with that type of route.

vars
object, optional

Custom variables stored for this scheduled message (copied to each ScheduledMessage and Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

label_ids
array of string IDs of Label, optional

IDs of labels to add to the Message

Return Type

Client libraries: undefined

Raw API: RelativeScheduledMessage

Permission Required

Send messages

Example

Delete relative scheduled message

DELETE /v1/projects/<project_id>/relative_scheduled/<rel_scheduled_msg_id>

Deletes this relative scheduled message and any associated scheduled messages.

Arguments

None

Return Type

undefined

Permission Required

Send messages

Example

Get scheduled message by ID

GET /v1/projects/<project_id>/scheduled/<scheduled_msg_id>

Retrieves the scheduled message with the given ID.

Arguments

None

Return Type

ScheduledMessage

Permission Required

View messages

Example

Get relative scheduled message by ID

GET /v1/projects/<project_id>/relative_scheduled/<rel_scheduled_msg_id>

Retrieves the scheduled message with the given ID.

Arguments

None

Return Type

RelativeScheduledMessage

Permission Required

View messages

Example

Contacts

Object Type: Contact

Attributes

id
string, max 34 characters

ID of the contact

read-only
name
string

Name of the contact

updatable
phone_number
string

Phone number of the contact

updatable
time_created
UNIX timestamp

Time the contact was added in Telerivet

read-only
time_updated
UNIX timestamp

Time the contact was last updated in Telerivet

read-only
send_blocked
bool

True if Telerivet is blocked from sending messages to this contact

updatable
conversation_status
string

Current status of the conversation with this contact

Possible Values: closed, active, handled
updatable
last_message_time
UNIX timestamp

Last time the contact sent or received a message (null if no messages have been sent or received)

read-only
last_incoming_message_time
UNIX timestamp

Last time a message was received from this contact

read-only
last_outgoing_message_time
UNIX timestamp

Last time a message was sent to this contact

read-only
message_count
int

Total number of non-deleted messages sent to or received from this contact

read-only
incoming_message_count
int

Number of messages received from this contact

read-only
outgoing_message_count
int

Number of messages sent to this contact

read-only
last_message_id
string ID of Message

ID of the last message sent to or received from this contact (null if no messages have been sent or received)

read-only
default_route_id
string ID of Phone

ID of the basic route (phone) or custom route that Telerivet will use by default to send messages to this contact (null if using project default route)

updatable
group_ids
array of strings

List of IDs of groups that this contact belongs to

read-only
vars
object

Custom variables stored for this contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this contact belongs to

read-only

Example

{
 "id": "CTa1299c3d0e371023",
 "name": "John Smith",
 "phone_number": "+16505550123",
 "time_created": 1390348075,
 "time_updated": 1390348099,
 "send_blocked": false,
 "conversation_status": "active",
 "last_message_time": 1395881121,
 "last_incoming_message_time": 1395881121,
 "last_outgoing_message_time": 1395881032,
 "message_count": 13,
 "incoming_message_count": 2,
 "outgoing_message_count": 11,
 "last_message_id": "SM97f47ac232df154d",
 "default_route_id": null,
 "group_ids": [
  "CGb0b7201b222fa609",
  "CG5f5ff672ebdd6766"
 ],
 "vars": {
  "email": "jsmith@example.com",
  "birthdate": "1953-01-05"
 },
 "project_id": "PJ2ad0100821a98bea",
 "url": "https://telerivet.com/p/asdf/contact/CTa1299c3d0e371023"
}

Create, update, or retrieve a contact

POST /v1/projects/<project_id>/contacts

Retrieves OR creates and possibly updates a contact by name or phone number.

If a phone number is provided, by default, Telerivet will search for an existing contact with that phone number (including suffix matches to allow finding contacts with phone numbers in a different format). If a phone number is not provided but a name is provided, Telerivet will search for a contact with that exact name (case insensitive). This behavior can be modified by setting the lookup_key parameter to look up a contact by another field, including a custom variable.

If no existing contact is found, a new contact will be created.

Then that contact will be updated with any parameters provided (name, phone_number, vars, default_route_id, send_blocked, add_group_ids, remove_group_ids).

Arguments

name
string, optional

Name of the contact

phone_number
string, optional

Phone number of the contact

lookup_key
string, optional

The field used to search for a matching contact, or 'none' to always create a new contact. To search by a custom variable, precede the variable name with 'vars.'.

Possible Values: phone_number, name, id, vars.variable_name, none
Default: phone_number
send_blocked
bool, optional

True if Telerivet is blocked from sending messages to this contact

default_route_id
string ID of Route, optional

ID of the route to use by default to send messages to this contact

add_group_ids
array of string IDs of Group, optional

ID of one or more groups to add this contact as a member (max 20)

id
string ID of Contact, optional

ID of an existing contact (only used if lookup_key is 'id')

remove_group_ids
array of string IDs of Group, optional

ID of one or more groups to remove this contact as a member (max 20)

vars
object, optional

Custom variables and values to update on the contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Contact

Permission Required

Edit contacts

Example

Query contacts

GET /v1/projects/<project_id>/contacts

Queries contacts within the given project.

Arguments

group_id
string ID of Group, optional

Filter contacts within a group

name
string, optional

Filter contacts by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
phone_number
string, optional

Filter contacts by phone number

Allowed Modifiers: phone_number[ne], phone_number[prefix], phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt], phone_number[lte], phone_number[exists] (?)
time_created
UNIX timestamp, optional

Filter contacts by time created

Allowed Modifiers: time_created[min], time_created[max] (?)
last_message_time
UNIX timestamp, optional

Filter contacts by last time a message was sent or received

Allowed Modifiers: last_message_time[min], last_message_time[max], last_message_time[exists] (?)
last_incoming_message_time
UNIX timestamp, optional

Filter contacts by last time a message was received

Allowed Modifiers: last_incoming_message_time[min], last_incoming_message_time[max], last_incoming_message_time[exists] (?)
last_outgoing_message_time
UNIX timestamp, optional

Filter contacts by last time a message was sent

Allowed Modifiers: last_outgoing_message_time[min], last_outgoing_message_time[max], last_outgoing_message_time[exists] (?)
incoming_message_count
int, optional

Filter contacts by number of messages received from the contact

Allowed Modifiers: incoming_message_count[ne], incoming_message_count[min], incoming_message_count[max] (?)
outgoing_message_count
int, optional

Filter contacts by number of messages sent to the contact

Allowed Modifiers: outgoing_message_count[ne], outgoing_message_count[min], outgoing_message_count[max] (?)
send_blocked
bool, optional

Filter contacts by blocked status

vars
object, optional

Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)

Allowed Modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min], vars[foo][max], vars[foo][exists] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name, phone_number, last_message_time
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Contact

Raw API: Query result of Contact

Permission Required

View contacts

Example

Import contacts

POST /v1/projects/<project_id>/import_contacts

Creates and/or updates up to 200 contacts in a single API call. When creating or updating a large number of contacts, this method is significantly faster than sending a separate API request for each contact.

By default, if the phone number for any contact matches an existing contact, the existing contact will be updated with any information provided. This behavior can be modified by setting the lookup_key parameter to look up contacts by another field, including a custom variable.

If any contact was not found matching the provided lookup_key, a new contact will be created.

Arguments

contacts
array, required

Array of up to 200 objects which may contain the properties name (string), phone_number (string), vars (object), and send_blocked (boolean). All properties are optional, unless used as a lookup key; however, either a name or phone_number property must be provided for new contacts.

lookup_key
string, optional

The field used to search for a matching contact, or 'none' to always create a new contact. To search by a custom variable, precede the variable name with 'vars.'.

Possible Values: phone_number, id, vars.variable_name, none
Default: phone_number
add_group_ids
array of string IDs of Group, optional

ID of one or more groups to add these contacts as members (max 5)

remove_group_ids
array of string IDs of Group, optional

ID of one or more groups to remove these contacts as members (max 5)

default_route_id
string ID of Route, optional

ID of the route to use by default to send messages to these contacts

Return Type

object

Return Value Properties

contacts
array

List of objects representing each contact, with the same length and order as provided in the contacts parameter in the API request. Each object has a string id property.

Permission Required

Edit contacts

Example

Delete a contact

DELETE /v1/projects/<project_id>/contacts/<contact_id>

Deletes this contact.

Arguments

None

Return Type

undefined

Permission Required

Edit contacts

Example

Get custom contact fields

GET /v1/projects/<project_id>/contact_fields

Gets a list of all custom fields defined for contacts in this project. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and 'lookup_key'. (Fields are automatically created any time a Contact's 'vars' property is updated.)

Arguments

None

Return Type

array

Permission Required

View contacts

Example

Get contact by ID

GET /v1/projects/<project_id>/contacts/<contact_id>

Retrieves the contact with the given ID.

Arguments

None

Return Type

Contact

Permission Required

View contacts

Example

Update contact details

POST /v1/projects/<project_id>/contacts/<contact_id>

Updates writable fields on the given contact

Arguments

name
string, optional

Name of the contact

phone_number
string, optional

Phone number of the contact

send_blocked
bool, optional

True if Telerivet is blocked from sending messages to this contact

conversation_status
string, optional

Current status of the conversation with this contact

Possible Values: closed, active, handled
default_route_id
string ID of Phone, optional

ID of the basic route (phone) or custom route that Telerivet will use by default to send messages to this contact (null if using project default route)

vars
object, optional

Custom variables stored for this contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: Contact

Permission Required

Edit contacts

Example

Query messages sent or received by a contact

GET /v1/projects/<project_id>/contacts/<contact_id>/messages

Queries messages sent or received by this contact.

Arguments

direction
string, optional

Filter messages by direction

Possible Values: incoming, outgoing
message_type
string, optional

Filter messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
source
string, optional

Filter messages by source

Possible Values: phone, provider, web, api, service, webhook, scheduled, integration
starred
bool, optional

Filter messages by starred/unstarred

status
string, optional

Filter messages by status

Possible Values: ignored, processing, received, sent, queued, failed, failed_queued, cancelled, delivered, not_delivered, read
time_created[min]
UNIX timestamp, optional

Filter messages created on or after a particular time

time_created[max]
UNIX timestamp, optional

Filter messages created before a particular time

external_id
string, optional

Filter messages by ID from an external provider

Allowed Modifiers: external_id[ne], external_id[exists] (?)
contact_id
string ID of Contact, optional

ID of the contact who sent/received the message

Allowed Modifiers: contact_id[ne], contact_id[exists] (?)
phone_id
string ID of Phone, optional

ID of the phone (basic route) that sent/received the message

broadcast_id
string ID of Broadcast, optional

ID of the broadcast containing the message

Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?)
scheduled_id
string ID of ScheduledMessage, optional

ID of the scheduled message that created this message

Allowed Modifiers: scheduled_id[ne], scheduled_id[exists] (?)
group_id
string ID of Group, optional

Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group.

sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Message

Raw API: Query result of Message

Permission Required

View messages

Example

Remove contact from a group

DELETE /v1/projects/<project_id>/groups/<group_id>/contacts/<contact_id>

Removes this contact from a group.

Arguments

None

Return Type

undefined

Permission Required

Edit contacts

Example

Add contact to a group

PUT /v1/projects/<project_id>/groups/<group_id>/contacts/<contact_id>

Adds this contact to a group.

Arguments

None

Return Type

undefined

Permission Required

Edit contacts

Example

Query service states for a contact

GET /v1/projects/<project_id>/contacts/<contact_id>/states

Queries this contact's current states for any service

Arguments

id
string, optional

Filter states by id

Allowed Modifiers: id[ne], id[prefix], id[not_prefix], id[gte], id[gt], id[lt], id[lte] (?)
vars
object, optional

Filter states by value of a custom variable (e.g. vars[email], vars[foo], etc.)

Allowed Modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min], vars[foo][max], vars[foo][exists] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of ContactServiceState

Raw API: Query result of ContactServiceState

Permission Required

View contacts

Example

Query data rows for a contact

GET /v1/projects/<project_id>/contacts/<contact_id>/rows

Queries data rows associated with this contact (in any data table).

Arguments

time_created
UNIX timestamp, optional

Filter data rows by the time they were created

Allowed Modifiers: time_created[min], time_created[max] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of DataRow

Raw API: Query result of DataRow

Permission Required

View data tables

Example

Query scheduled messages for a contact

GET /v1/projects/<project_id>/contacts/<contact_id>/scheduled

Queries messages scheduled to this contact (not including messages scheduled to groups that this contact is a member of)

Arguments

message_type
string, optional

Filter scheduled messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
time_created
UNIX timestamp, optional

Filter scheduled messages by time_created

Allowed Modifiers: time_created[min], time_created[max] (?)
next_time
UNIX timestamp, optional

Filter scheduled messages by next_time

Allowed Modifiers: next_time[min], next_time[max], next_time[exists] (?)
relative_scheduled_id
string ID of RelativeScheduledMessage, optional

Filter scheduled messages created for a relative scheduled message

sort
string, optional

Sort the results based on a field

Possible Values: default, next_time
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of ScheduledMessage

Raw API: Query result of ScheduledMessage

Permission Required

View messages

Example

Query groups for a contact

GET /v1/projects/<project_id>/contacts/<contact_id>/groups

Queries groups for which this contact is a member.

Arguments

name
string, optional

Filter groups by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
dynamic
bool, optional

Filter groups by dynamic/non-dynamic

sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Group

Raw API: Query result of Group

Permission Required

View contacts

Example

Update contact field metadata

POST /v1/projects/<project_id>/contact_fields/<variable>

Allows customizing how a custom contact field is displayed in the Telerivet web app.

The variable path parameter can contain the characters a-z, A-Z, 0-9, and _, and may be up to 32 characters in length.

Arguments

name
string, max 64 characters, optional

Display name for the field

type
int, optional

Field type

Possible Values: text, long_text, secret, phone_number, email, url, audio, date, date_time, number, boolean, checkbox, select, radio, route
order
int, optional

Order in which to display the field

items
array, required if type is `select`

Array of up to 100 objects containing value and label string properties to show in the dropdown list when type is select. Each value and label must be between 1 and 256 characters in length.

readonly
bool, optional

Set to true to prevent editing the field in the Telerivet web app

lookup_key
bool, optional

Set to true to allow using this field as a lookup key when importing contacts via the Telerivet web app

show_on_conversation
bool, optional

Set to true to show field on Conversations tab

Return Type

object

Permission Required

Edit contacts

Example

Routes

Object Type: Phone

Represents a basic route (i.e. a phone or gateway) that you use to send/receive messages via Telerivet.

Basic Routes were formerly referred to as "Phones" within Telerivet. API methods, parameters, and properties related to Basic Routes continue to use the term "Phone" to maintain backwards compatibility.

Attributes

id
string, max 34 characters

ID of the phone

read-only
name
string

Name of the phone

updatable
phone_number
string

Phone number or sender ID

updatable
phone_type
string

Type of this phone/route (e.g. android, twilio, nexmo, etc)

read-only
country
string

2-letter country code (ISO 3166-1 alpha-2) where phone is from

read-only
send_paused
bool

True if sending messages is currently paused, false if the phone can currently send messages

updatable
time_created
UNIX timestamp

Time the phone was created in Telerivet

read-only
last_active_time
UNIX timestamp

Approximate time this phone last connected to Telerivet

read-only
vars
object

Custom variables stored for this phone. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this phone belongs to

read-only
battery
int

Current battery level, on a scale from 0 to 100, as of the last time the phone connected to Telerivet (only present for Android phones)

read-only
charging
bool

True if the phone is currently charging, false if it is running on battery, as of the last time it connected to Telerivet (only present for Android phones)

read-only
internet_type
string

String describing the current type of internet connectivity for an Android phone, for example WIFI or MOBILE (only present for Android phones)

read-only
app_version
string

Currently installed version of Telerivet Android app (only present for Android phones)

read-only
android_sdk
int

Android SDK level, indicating the approximate version of the Android OS installed on this phone; see list of Android SDK levels (only present for Android phones)

read-only
mccmnc
string

Code indicating the Android phone's current country (MCC) and mobile network operator (MNC); see Mobile country code Wikipedia article (only present for Android phones). Note this is a string containing numeric digits, not an integer.

read-only
manufacturer
string

Android phone manufacturer (only present for Android phones)

read-only
model
string

Android phone model (only present for Android phones)

read-only
send_limit
int

Maximum number of SMS messages per hour that can be sent by this Android phone. To increase this limit, install additional SMS expansion packs in the Telerivet Gateway app. (only present for Android phones)

read-only

Example

{
 "id": "PN4d246818d0ecd1fa",
 "name": "Android Phone 1",
 "phone_number": "+16505550001",
 "phone_type": "android",
 "country": "TZ",
 "send_paused": false,
 "time_created": 1390343779,
 "last_active_time": 1390353800,
 "vars": {
  "foo": 42
 },
 "project_id": "PJ2ad0100821a98bea",
 "battery": 95,
 "charging": false,
 "internet_type": "WIFI",
 "app_version": "3.1.17",
 "android_sdk": 17,
 "mccmnc": "23203",
 "manufacturer": "LGE",
 "model": "Nexus 4",
 "send_limit": 900,
 "url": "https://telerivet.com/p/asdf/phone/PN4d246818d0ecd1fa"
}

Object Type: Route

Represents a custom route that can be used to send messages via one or more basic routes (phones).

Custom Routes were formerly referred to simply as "Routes" within Telerivet. API methods, parameters, and properties related to Custom Routes continue to use the term "Route" to maintain backwards compatibility.

Custom routing rules can currently only be configured via Telerivet's web UI.

Attributes

id
string, max 34 characters

Telerivet's internal ID for the route

read-only
name
string

The name of the route

updatable
vars
object

Custom variables stored for this route. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this route belongs to

read-only

Example

{
 "id": "RTed8af84c2679ac09",
 "name": "Custom Route",
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "project_id": "PJ2ad0100821a98bea"
}

Query basic routes

GET /v1/projects/<project_id>/phones

Queries basic routes within the given project.

Arguments

name
string, optional

Filter phones by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
phone_number
string, optional

Filter phones by phone number

Allowed Modifiers: phone_number[ne], phone_number[prefix], phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt], phone_number[lte] (?)
last_active_time
UNIX timestamp, optional

Filter phones by last active time

Allowed Modifiers: last_active_time[min], last_active_time[max], last_active_time[exists] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name, phone_number
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Phone

Raw API: Query result of Phone

Permission Required

View routes

Example

Get basic route by ID

GET /v1/projects/<project_id>/phones/<phone_id>

Retrieves the basic route with the given ID.

Arguments

None

Return Type

Phone

Permission Required

View routes

Example

Query custom routes

GET /v1/projects/<project_id>/routes

Queries custom routes that can be used to send messages (not including Phones).

Arguments

name
string, optional

Filter routes by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Route

Raw API: Query result of Route

Permission Required

View routes

Example

Get custom route by ID

GET /v1/projects/<project_id>/routes/<route_id>

Gets a custom route by ID

Arguments

None

Return Type

Route

Permission Required

View routes

Example

Query messages for a basic route

GET /v1/projects/<project_id>/phones/<phone_id>/messages

Queries messages sent or received by this basic route.

Arguments

direction
string, optional

Filter messages by direction

Possible Values: incoming, outgoing
message_type
string, optional

Filter messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
source
string, optional

Filter messages by source

Possible Values: phone, provider, web, api, service, webhook, scheduled, integration
starred
bool, optional

Filter messages by starred/unstarred

status
string, optional

Filter messages by status

Possible Values: ignored, processing, received, sent, queued, failed, failed_queued, cancelled, delivered, not_delivered, read
time_created[min]
UNIX timestamp, optional

Filter messages created on or after a particular time

time_created[max]
UNIX timestamp, optional

Filter messages created before a particular time

external_id
string, optional

Filter messages by ID from an external provider

Allowed Modifiers: external_id[ne], external_id[exists] (?)
contact_id
string ID of Contact, optional

ID of the contact who sent/received the message

Allowed Modifiers: contact_id[ne], contact_id[exists] (?)
phone_id
string ID of Phone, optional

ID of the phone (basic route) that sent/received the message

broadcast_id
string ID of Broadcast, optional

ID of the broadcast containing the message

Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?)
scheduled_id
string ID of ScheduledMessage, optional

ID of the scheduled message that created this message

Allowed Modifiers: scheduled_id[ne], scheduled_id[exists] (?)
group_id
string ID of Group, optional

Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group.

sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Message

Raw API: Query result of Message

Permission Required

View messages

Example

Update basic route

POST /v1/projects/<project_id>/phones/<phone_id>

Updates writable fields on the given basic route.

Arguments

name
string, optional

Name of the phone

phone_number
string, optional

Phone number or sender ID

send_paused
bool, optional

True if sending messages is currently paused, false if the phone can currently send messages

vars
object, optional

Custom variables stored for this phone. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: Phone

Permission Required

Edit routes

Example

Update custom route

POST /v1/projects/<project_id>/routes/<route_id>

Saves any fields or custom variables that have changed for this custom route.

Arguments

name
string, optional

The name of the route

vars
object, optional

Custom variables stored for this route. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: Route

Permission Required

Edit routes

Example

Services

Object Type: Service

Represents an automated service on Telerivet, for example a poll, auto-reply, webhook service, etc.

A service, generally, defines some automated behavior that can be invoked/triggered in a particular context, and may be invoked either manually or when a particular event occurs.

Most commonly, services work in the context of a particular message, when the message is originally received by Telerivet.

Attributes

id
string, max 34 characters

ID of the service

read-only
name
string

Name of the service

updatable
service_type
string

Type of the service.

read-only
active
bool

Whether the service is active or inactive. Inactive services are not automatically triggered and cannot be invoked via the API.

updatable
priority
int

A number that determines the order that services are triggered when a particular event occurs (smaller numbers are triggered first). Any service can determine whether or not execution "falls-through" to subsequent services (with larger priority values) by setting the return_value variable within Telerivet's Rules Engine.

updatable
contexts
object

A key/value map where the keys are the names of contexts supported by this service (e.g. message, contact), and the values are themselves key/value maps where the keys are event names and the values are all true. (This structure makes it easy to test whether a service can be invoked for a particular context and event.)

read-only
vars
object

Custom variables stored for this service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this service belongs to

read-only
response_table_id
string ID of DataTable

ID of the data table where responses to this service will be stored

updatable
phone_ids
string

IDs of phones (basic routes) associated with this service, or null if the service is associated with all routes. Only applies for service types that handle incoming messages, voice calls, or USSD sessions.

updatable
apply_mode
string

If apply_mode is unhandled, the service will not be triggered if another service has already handled the incoming message. If apply_mode is always, the service will always be triggered regardless of other services. Only applies to services that handle incoming messages.

Possible Values: always, unhandled
updatable
contact_number_filter
string

If contact_number_filter is long_number, this service will only be triggered if the contact phone number has at least 7 digits (ignoring messages from shortcodes and alphanumeric senders). If contact_number_filter is all, the service will be triggered for all contact phone numbers. Only applies to services that handle incoming messages.

Possible Values: long_number, all
updatable
show_action
bool

Whether this service is shown in the 'Actions' menu within the Telerivet web app when the service is active. Only provided for service types that are manually triggered.

updatable
direction
string

Determines whether the service handles incoming voice calls, outgoing voice calls, or both. Only applies to services that handle voice calls.

Possible Values: incoming, outgoing, both
updatable
webhook_url
string

URL that a third-party can invoke to trigger this service. Only provided for services that are triggered by a webhook request.

read-only

Example

{
 "id": "SVee45c8ae4e32889a",
 "name": "Poll Service",
 "service_type": "messaging_poll",
 "active": true,
 "priority": 1,
 "contexts": {
  "message": {
   "incoming_message": true
  },
  "contact": {
   "default": true
  }
 },
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "project_id": "PJ2ad0100821a98bea",
 "response_table_id": "DTf9fe14d9c306aed9",
 "phone_ids": null,
 "apply_mode": null,
 "contact_number_filter": null,
 "show_action": null,
 "direction": null,
 "webhook_url": null
}

Object Type: ContactServiceState

Represents the current state of a particular contact for a particular Telerivet service.

Some automated services (including polls) are 'stateful'. For polls, Telerivet needs to keep track of which question the contact is currently answering, and stores store the ID of each contact's current question (e.g. 'q1' or 'q2') as the ID of the contact's state for the poll service. Any type of conversation-like service will also need to store state for each contact.

For this type of entity, the 'id' field is NOT a read-only unique ID (unlike all other types of entities). Instead it is an arbitrary string that identifies the contact's current state within your poll/conversation; many contacts may have the same state ID, and it may change over time. Additional custom fields may be stored in the 'vars'.

Initially, the state 'id' for any contact is null. When saving the state, setting the 'id' to null is equivalent to resetting the state (so all 'vars' will be deleted); if you want to save custom variables, the state 'id' must be non-null.

Many Telerivet services are stateless, such as auto-replies or keyword-based services where the behavior only depends on the current message, and not any previous messages sent by the same contact. Telerivet doesn't store any state for contacts that interact with stateless services.

Attributes

id
string, max 63 characters

Arbitrary string representing the contact's current state for this service, e.g. 'q1', 'q2', etc.

updatable
contact_id
string ID of Contact

ID of the contact

read-only
service_id
string ID of Service

ID of the service

read-only
vars
object

Custom variables stored for this contact/service state. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
time_created
UNIX timestamp

Time the state was first created in Telerivet

read-only
time_updated
UNIX timestamp

Time the state was last updated in Telerivet

read-only
project_id
string ID of Project

ID of the project this contact/service state belongs to

read-only

Example

{
 "id": "q1",
 "contact_id": "CTa1299c3d0e371023",
 "service_id": "SVee45c8ae4e32889a",
 "vars": {
  "q1": "yes",
  "q2": "no"
 },
 "time_created": 1395617416,
 "time_updated": 1395617440,
 "project_id": "PJ2ad0100821a98bea"
}

Invoke a service

POST /v1/projects/<project_id>/services/<service_id>/invoke

Manually invoke this service in a particular context.

For example, to send a poll to a particular contact (or resend the current question), you can invoke the poll service with context=contact, and contact_id as the ID of the contact to send the poll to. (To trigger a service to multiple contacts, use project.sendBroadcast. To schedule a service in the future, use project.scheduleMessage.)

Or, to manually apply a service for an incoming message, you can invoke the service with context=message, event=incoming_message, and message_id as the ID of the incoming message. (This is normally not necessary, but could be used if you want to override Telerivet's standard priority-ordering of services.)

Arguments

context
string, required

The name of the context in which this service is invoked

Possible Values: message, call, ussd_session, row, contact, project
event
string, optional

The name of the event that is triggered (must be supported by this service)

Default: default
message_id
string ID of Message, required if context is 'message'

The ID of the message this service is triggered for

contact_id
string ID of Contact, optional

The ID of the contact this service is triggered for (either contact_id or phone_number is required if context is 'contact')

phone_number
string, optional

The phone number of the contact this service is triggered for (either contact_id or phone_number is required if context is 'contact'). If no contact exists with this phone number, a new contact will be created.

variables
object, optional

Object containing up to 25 temporary variable names and their corresponding values to set when invoking the service. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Within Custom Actions, each variable can be used like [[$name]] (with a leading $ character and surrounded by double square brackets). Within a Cloud Script API service or JavaScript action, each variable will be available as a global JavaScript variable like $name (with a leading $ character).

route_id
string, optional

The ID of the phone or route that the service will use for sending messages by default

async
bool, optional

If set to true, the service will be invoked asynchronously. By default, queued services will be invoked one at a time for each project.

Return Type

object

Return Value Properties

return_value
any

Return value of the service. May be any JSON type (boolean, number, string, array, object, or null). (Undefined if async=true.)

log_entries
array

Array of log entry strings generated by the service. (Undefined if async=true.)

errors
array

Array of error message strings generated by the service. (Undefined if async=true.)

sent_messages
array of objects

Array of messages sent by the service.

airtime_transactions
array of objects

Array of airtime transactions sent by the service (Undefined if async=true.)

Permission Required

Send messages

Example

Create a service

POST /v1/projects/<project_id>/services

Creates a new automated service.

Only certain types of automated services can be created via the API. Other types of services can only be created via the web app.

Although Custom Actions services cannot be created directly via the API, they may be converted to a template, and then instances of the template can be created via this method with service_type=custom_template_instance. Converting a service to a template requires the Service Templates feature to be enabled for the organization.

Arguments

name
string, optional

Name of the service to create, which must be unique in the project. If a name is not provided, a unique default name will be generated.

service_type
string, required

Type of service to create. The following service types can be created via the API:

  • incoming_message_webhook
  • incoming_message_script
  • contact_script
  • message_script
  • data_row_script
  • webhook_script
  • voice_script
  • ussd_script
  • project_script
  • custom_template_instance

Other types of services can only be created via the web app.

config
object, required

Configuration specific to the service type.

incoming_message_webhook:

url The webhook URL that will be triggered when an incoming message is received (string)
secret Optional string that will be passed as the `secret` POST parameter to the webhook URL. (object)


incoming_message_script, contact_script, message_script, data_row_script, webhook_script, voice_script, ussd_script, project_script:

code The JavaScript code to run when the service is triggered (max 100 KB). To run code longer than 100 KB, use a Cloud Script Module. (string)


custom_template_instance:

template_service_id ID of the service template (string). The service template must be available to the current project or organization.
params Key/value pairs for all service template parameters (object). If the values satisfy the validation rules specified in the service template, they will also be copied to the `vars` property of the service. Any values not associated with service template parameters will be ignored.


vars
string, optional

Custom variables and values to set for this service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

active
bool, optional

Whether the service is initially active or inactive. Inactive services are not automatically triggered and cannot be invoked via the API.

Default: true
response_table_id
string ID of DataTable, optional

ID of a data table where responses will be stored, or null to disable automatically storing responses. If the response_table_id parameter is not provided, a data table may automatically be created with the same name as the service if the service collects responses.

phone_ids
array of string IDs of Phone, optional

IDs of phones (basic routes) to associate with this service, or null to associate this service with all routes. Only applies for service types that handle incoming messages, voice calls, or USSD sessions.

message_types
array, optional

Types of messages that this service should handle. Only applies to services that handle incoming messages.

Possible Values: text, call, sms, mms, ussd_session, chat
show_action
bool, optional

Whether to show this service in the Actions menu within the Telerivet web app when the service is active. Only applies for service types that are manually triggered.

Default: true
contact_number_filter
string, optional

If contact_number_filter is long_number, this service will only be triggered if the contact phone number has at least 7 digits (ignoring messages from shortcodes and alphanumeric senders). If contact_number_filter is all, the service will be triggered for all contact phone numbers. Only applies to services that handle incoming messages.

Possible Values: long_number, all
Default: long_number
direction
string, optional

Determines whether the service handles incoming voice calls, outgoing voice calls, or both. Only applies to services that handle voice calls.

Possible Values: incoming, outgoing, both
Default: both
priority
int, optional

A number that determines the order that services are triggered when an event occurs (e.g. when an incoming message is received). Smaller numbers are triggered first. The priority is ignored for services that are triggered directly.

apply_mode
string, optional

If apply_mode is unhandled, the service will not be triggered if another service has already handled the incoming message. If apply_mode is always, the service will always be triggered regardless of other services. Only applies to services that handle incoming messages.

Possible Values: always, unhandled
Default: unhandled

Return Type

Service

Permission Required

Edit automated services

Example

Query services

GET /v1/projects/<project_id>/services

Queries services within the given project.

Arguments

name
string, optional

Filter services by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
active
bool, optional

Filter services by active/inactive state

context
string, optional

Filter services that can be invoked in a particular context

Possible Values: message, call, ussd_session, row, contact, project
sort
string, optional

Sort the results based on a field

Possible Values: default, priority, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Service

Raw API: Query result of Service

Permission Required

View automated services

Example

Get service by ID

GET /v1/projects/<project_id>/services/<service_id>

Retrieves the service with the given ID.

Arguments

None

Return Type

Service

Permission Required

View automated services

Example

Update service configuration

POST /v1/projects/<project_id>/services/<service_id>/config

Updates configuration specific to the type of automated service.

Only certain types of services support updating their configuration via the API.

Note: when updating a service of type custom_template_instance, the validation script will be invoked when calling this method.

Arguments

Configuration for this service type. See project.createService for available configuration options.

Return Type

object

Permission Required

Edit automated services

Example

Get service configuration

GET /v1/projects/<project_id>/services/<service_id>/config

Gets configuration specific to the type of automated service.

Only certain types of services provide their configuration via the API.

Arguments

None

Return Type

object

Permission Required

View automated services

Example

Update service details

POST /v1/projects/<project_id>/services/<service_id>

Updates writable fields on the given service.

Arguments

name
string, optional

Name of the service

active
bool, optional

Whether the service is active or inactive. Inactive services are not automatically triggered and cannot be invoked via the API.

priority
int, optional

A number that determines the order that services are triggered when a particular event occurs (smaller numbers are triggered first). Any service can determine whether or not execution "falls-through" to subsequent services (with larger priority values) by setting the return_value variable within Telerivet's Rules Engine.

vars
object, optional

Custom variables stored for this service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

response_table_id
string ID of DataTable, optional

ID of the data table where responses to this service will be stored

phone_ids
string, optional

IDs of phones (basic routes) associated with this service, or null if the service is associated with all routes. Only applies for service types that handle incoming messages, voice calls, or USSD sessions.

apply_mode
string, optional

If apply_mode is unhandled, the service will not be triggered if another service has already handled the incoming message. If apply_mode is always, the service will always be triggered regardless of other services. Only applies to services that handle incoming messages.

Possible Values: always, unhandled
contact_number_filter
string, optional

If contact_number_filter is long_number, this service will only be triggered if the contact phone number has at least 7 digits (ignoring messages from shortcodes and alphanumeric senders). If contact_number_filter is all, the service will be triggered for all contact phone numbers. Only applies to services that handle incoming messages.

Possible Values: long_number, all
show_action
bool, optional

Whether this service is shown in the 'Actions' menu within the Telerivet web app when the service is active. Only provided for service types that are manually triggered.

direction
string, optional

Determines whether the service handles incoming voice calls, outgoing voice calls, or both. Only applies to services that handle voice calls.

Possible Values: incoming, outgoing, both

Return Type

Client libraries: undefined

Raw API: Service

Permission Required

Edit automated services

Example

Query service logs

GET /v1/projects/<project_id>/service_logs

Queries service log entries associated with this project.

Note: Service logs are automatically deleted and no longer available via the API after approximately one month.

Arguments

service_id
string ID of Service, optional

Filter logs generated by a particular service

message_id
string ID of Message, optional

Filter service logs related to a particular message

contact_id
string ID of Contact, optional

Filter service logs related to a particular contact. Ignored if using the message_id parameter.

time_created
UNIX timestamp, optional

Filter service logs by the time they were created

Allowed Modifiers: time_created[min], time_created[max] (?)
execution_stats
bool, optional

Show detailed execution stats for each log entry, if available.

sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of object

Returned Item Properties

time_created
UNIX timestamp

The time when the log entry was created

content
string

The text logged

elapsed_ms
int

Elapsed time in milliseconds, if available.

service_id
string

ID of the service associated with this log entry. Not returned when querying log entries for a particular service.

message_id
string

ID of the message associated with this log entry. Not returned when querying log entries for a particular message.

contact_id
string

ID of the contact associated with this log entry. Not returned when querying log entries for a particular message or contact.

api_request_count
int

The total number of API requests triggered via the Cloud Script API. (Only provided if execution_stats=true.)

api_request_ms
int

The total execution time of all API requests triggered via the Cloud Script API. (Only provided if execution_stats=true.)

http_request_count
int

The total number of external HTTP requests triggered via the Cloud Script API. (Only provided if execution_stats=true.)

http_request_ms
int

The total execution time of all external HTTP requests triggered via the Cloud Script API. (Only provided if execution_stats=true.)

webhook_count
int

The total number of Webhook API requests triggered. (Only provided if execution_stats=true.)

requests
array

Details about each API request, external HTTP request, and Cloud Script Module loaded via the Cloud Script API. (Only provided if execution_stats=true.)

Each item in the array has the following properties:

  • type (string): api_request, http_request, or module_load
  • resource (string): A string specific to the type of request. For module_load, this is the module path. For api_request, it contains the HTTP method, path, and query string. For http_request, it contains the HTTP method and URL.
  • elapsed_ms (int): Number of milliseconds elapsed in fetching this resource
  • status_code (int): Response status code, if available

Raw API: Query result of object

Permission Required

View automated services

Example

Query contacts' states for a service

GET /v1/projects/<project_id>/services/<service_id>/states

Query the current states of contacts for this service.

Arguments

id
string, optional

Filter states by id

Allowed Modifiers: id[ne], id[prefix], id[not_prefix], id[gte], id[gt], id[lt], id[lte] (?)
vars
object, optional

Filter states by value of a custom variable (e.g. vars[email], vars[foo], etc.)

Allowed Modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min], vars[foo][max], vars[foo][exists] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of ContactServiceState

Raw API: Query result of ContactServiceState

Permission Required

View contacts

Example

Get a contact's state for a service

GET /v1/projects/<project_id>/services/<service_id>/states/<contact_id>

Gets the current state for a particular contact for this service.

If the contact doesn't already have a state, this method will return a valid state object with id=null. However this object would not be returned by queryContactStates() unless it is saved with a non-null state id.

Arguments

None

Return Type

ContactServiceState

Permission Required

View contacts

Example

Update a contact's state for a service

POST /v1/projects/<project_id>/services/<service_id>/states/<contact_id>

Initializes or updates the current state for a particular contact for the given service. If the state id is null, the contact's state will be reset.

Arguments

id
string, max 63 characters, required

Arbitrary string representing the contact's current state for this service, e.g. 'q1', 'q2', etc.

vars
object, optional

Custom variables stored for this contact's state. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

ContactServiceState

Permission Required

Edit contacts

Example

Reset a contact's state for a service

DELETE /v1/projects/<project_id>/services/<service_id>/states/<contact_id>

Resets the current state for a particular contact for the given service.

Arguments

None

Return Type

ContactServiceState

Permission Required

Edit contacts

Example

Delete a service

DELETE /v1/projects/<project_id>/services/<service_id>

Deletes this service.

Arguments

None

Return Type

undefined

Permission Required

Edit automated services

Example

Labels

Object Type: Label

Represents a label used to organize messages within Telerivet.

Attributes

id
string, max 34 characters

ID of the label

read-only
name
string

Name of the label

updatable
time_created
UNIX timestamp

Time the label was created in Telerivet

read-only
vars
object

Custom variables stored for this label. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this label belongs to

read-only

Example

{
 "id": "LB4f3dac27154653e0",
 "name": "Important",
 "time_created": 1392254503,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "project_id": "PJ2ad0100821a98bea"
}

Query labels

GET /v1/projects/<project_id>/labels

Queries labels within the given project.

Arguments

name
string, optional

Filter labels by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Label

Raw API: Query result of Label

Permission Required

View messages

Example

Create or retrieve a label by name

POST /v1/projects/<project_id>/labels

Gets or creates a label by name.

Arguments

name
string, required

Name of the label

Return Type

Label

Permission Required

Send messages

Example

Get label by ID

GET /v1/projects/<project_id>/labels/<label_id>

Retrieves the label with the given ID.

Arguments

None

Return Type

Label

Permission Required

View messages

Example

Query messages with a label

GET /v1/projects/<project_id>/labels/<label_id>/messages

Queries messages with the given label.

Arguments

direction
string, optional

Filter messages by direction

Possible Values: incoming, outgoing
message_type
string, optional

Filter messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
source
string, optional

Filter messages by source

Possible Values: phone, provider, web, api, service, webhook, scheduled, integration
starred
bool, optional

Filter messages by starred/unstarred

status
string, optional

Filter messages by status

Possible Values: ignored, processing, received, sent, queued, failed, failed_queued, cancelled, delivered, not_delivered, read
time_created[min]
UNIX timestamp, optional

Filter messages created on or after a particular time

time_created[max]
UNIX timestamp, optional

Filter messages created before a particular time

external_id
string, optional

Filter messages by ID from an external provider

Allowed Modifiers: external_id[ne], external_id[exists] (?)
contact_id
string ID of Contact, optional

ID of the contact who sent/received the message

Allowed Modifiers: contact_id[ne], contact_id[exists] (?)
phone_id
string ID of Phone, optional

ID of the phone (basic route) that sent/received the message

broadcast_id
string ID of Broadcast, optional

ID of the broadcast containing the message

Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?)
scheduled_id
string ID of ScheduledMessage, optional

ID of the scheduled message that created this message

Allowed Modifiers: scheduled_id[ne], scheduled_id[exists] (?)
group_id
string ID of Group, optional

Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group.

sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Message

Raw API: Query result of Message

Permission Required

View messages

Example

Update label details

POST /v1/projects/<project_id>/labels/<label_id>

Updates writable fields on the given label.

Arguments

name
string, optional

Name of the label

vars
object, optional

Custom variables stored for this label. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: Label

Permission Required

Send messages

Example

Delete a label

DELETE /v1/projects/<project_id>/labels/<label_id>

Deletes the given label (Note: no messages are deleted.)

Arguments

None

Return Type

undefined

Permission Required

Send messages

Example

Groups

Object Type: Group

Represents a group used to organize contacts within Telerivet.

Attributes

id
string, max 34 characters

ID of the group

read-only
name
string

Name of the group

updatable
dynamic
bool

Whether this is a dynamic or normal group

read-only
num_members
int

Number of contacts in the group (null if the group is dynamic)

read-only
time_created
UNIX timestamp

Time the group was created in Telerivet

read-only
allow_sending
bool

True if messages can be sent to this group, false otherwise.

updatable
add_time_variable
string

Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable.

updatable
vars
object

Custom variables stored for this group. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this group belongs to

read-only

Example

{
 "id": "CGb0b7201b222fa609",
 "name": "Subscribers",
 "dynamic": false,
 "num_members": 142,
 "time_created": 1390343845,
 "allow_sending": null,
 "add_time_variable": "subscription_time",
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "project_id": "PJ2ad0100821a98bea"
}

Query groups

GET /v1/projects/<project_id>/groups

Queries groups within the given project.

Arguments

name
string, optional

Filter groups by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
dynamic
bool, optional

Filter groups by dynamic/non-dynamic

sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Group

Raw API: Query result of Group

Permission Required

View contacts

Example

Create or retrieve a group by name

POST /v1/projects/<project_id>/groups

Retrieves or creates a group by name.

Arguments

name
string, required

Name of the group

Return Type

Group

Permission Required

Edit contacts

Example

Get group by ID

GET /v1/projects/<project_id>/groups/<group_id>

Retrieves the group with the given ID.

Arguments

None

Return Type

Group

Permission Required

View contacts

Example

Query contacts in a group

GET /v1/projects/<project_id>/groups/<group_id>/contacts

Queries contacts that are members of the given group.

Arguments

name
string, optional

Filter contacts by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
phone_number
string, optional

Filter contacts by phone number

Allowed Modifiers: phone_number[ne], phone_number[prefix], phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt], phone_number[lte], phone_number[exists] (?)
time_created
UNIX timestamp, optional

Filter contacts by time created

Allowed Modifiers: time_created[min], time_created[max] (?)
last_message_time
UNIX timestamp, optional

Filter contacts by last time a message was sent or received

Allowed Modifiers: last_message_time[min], last_message_time[max], last_message_time[exists] (?)
last_incoming_message_time
UNIX timestamp, optional

Filter contacts by last time a message was received

Allowed Modifiers: last_incoming_message_time[min], last_incoming_message_time[max], last_incoming_message_time[exists] (?)
last_outgoing_message_time
UNIX timestamp, optional

Filter contacts by last time a message was sent

Allowed Modifiers: last_outgoing_message_time[min], last_outgoing_message_time[max], last_outgoing_message_time[exists] (?)
incoming_message_count
int, optional

Filter contacts by number of messages received from the contact

Allowed Modifiers: incoming_message_count[ne], incoming_message_count[min], incoming_message_count[max] (?)
outgoing_message_count
int, optional

Filter contacts by number of messages sent to the contact

Allowed Modifiers: outgoing_message_count[ne], outgoing_message_count[min], outgoing_message_count[max] (?)
send_blocked
bool, optional

Filter contacts by blocked status

vars
object, optional

Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)

Allowed Modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min], vars[foo][max], vars[foo][exists] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name, phone_number, last_message_time
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Contact

Raw API: Query result of Contact

Permission Required

View contacts

Example

Query scheduled messages to a group

GET /v1/projects/<project_id>/groups/<group_id>/scheduled

Queries scheduled messages to the given group.

Arguments

message_type
string, optional

Filter scheduled messages by message_type

Possible Values: sms, mms, ussd, ussd_session, call, chat, service
time_created
UNIX timestamp, optional

Filter scheduled messages by time_created

Allowed Modifiers: time_created[min], time_created[max] (?)
next_time
UNIX timestamp, optional

Filter scheduled messages by next_time

Allowed Modifiers: next_time[min], next_time[max], next_time[exists] (?)
relative_scheduled_id
string ID of RelativeScheduledMessage, optional

Filter scheduled messages created for a relative scheduled message

sort
string, optional

Sort the results based on a field

Possible Values: default, next_time
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of ScheduledMessage

Raw API: Query result of ScheduledMessage

Permission Required

View messages

Example

Update group details

POST /v1/projects/<project_id>/groups/<group_id>

Updates writable fields on the given group.

Arguments

name
string, optional

Name of the group

allow_sending
bool, optional

True if messages can be sent to this group, false otherwise.

add_time_variable
string, optional

Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable.

vars
object, optional

Custom variables stored for this group. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: Group

Permission Required

Edit contacts

Example

Delete a group

DELETE /v1/projects/<project_id>/groups/<group_id>

Deletes this group (Note: no contacts are deleted.)

Arguments

None

Return Type

undefined

Permission Required

Edit contacts

Example

Data Tables

Object Type: DataTable

Represents a custom data table that can store arbitrary rows.

For example, poll services use data tables to store a row for each response.

DataTables are schemaless -- each row simply stores custom variables. Each variable name is equivalent to a different "column" of the data table. Telerivet refers to these variables/columns as "fields", and automatically creates a new field for each variable name used in a row of the table.

Attributes

id
string, max 34 characters

ID of the data table

read-only
name
string

Name of the data table

updatable
num_rows
int

Number of rows in the table. For performance reasons, this number may sometimes be out-of-date.

read-only
show_add_row
bool

Whether to allow adding or importing rows via the web app

updatable
show_stats
bool

Whether to show summary charts (pie charts, bar charts, tables of top values) for this data table in the web app

updatable
show_contact_columns
bool

Whether to show 'Contact Name' and 'Phone Number' columns in the web app

updatable
vars
object

Custom variables stored for this data table. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
project_id
string ID of Project

ID of the project this data table belongs to

read-only

Example

{
 "id": "DTf9f77c9ba69cce50",
 "name": "Poll Responses",
 "num_rows": 1032,
 "show_add_row": false,
 "show_stats": true,
 "show_contact_columns": true,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "project_id": "PJ2ad0100821a98bea"
}

Object Type: DataRow

Represents a row in a custom data table.

For example, each response to a poll is stored as one row in a data table. If a poll has a question with ID 'q1', the verbatim response to that question would be stored in row.vars.q1, and the response code would be stored in row.vars.q1_code.

Each custom variable name within a data row corresponds to a different column/field of the data table.

Attributes

id
string, max 34 characters

ID of the data row

read-only
contact_id
string ID of Contact

ID of the contact this row is associated with (or null if not associated with any contact)

updatable
from_number
string

Phone number that this row is associated with (or null if not associated with any phone number)

updatable
vars
object

Custom variables stored for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
time_created
UNIX timestamp

The time this row was created in Telerivet

read-only
time_updated
UNIX timestamp

The time this row was last updated in Telerivet

read-only
table_id
string ID of DataTable

ID of the table this data row belongs to

read-only
project_id
string ID of Project

ID of the project this data row belongs to

read-only

Example

{
 "id": "DRd442e170d6133590",
 "contact_id": "CTa1299c3d0e371023",
 "from_number": "+16505550123",
 "vars": {
  "q1": "yes",
  "q2": "no"
 },
 "time_created": 1395102559,
 "time_updated": 1395102578,
 "table_id": "DTf9f77c9ba69cce50",
 "project_id": "PJ2ad0100821a98bea"
}

Create or retrieve a data table by name

POST /v1/projects/<project_id>/tables

Gets or creates a data table by name.

Arguments

name
string, required

Name of the data table

Return Type

DataTable

Permission Required

Edit data tables

Example

Get data table by ID

GET /v1/projects/<project_id>/tables/<table_id>

Retrieves the data table with the given ID.

Arguments

None

Return Type

DataTable

Permission Required

View data tables

Example

Query rows in a data table

GET /v1/projects/<project_id>/tables/<table_id>/rows

Queries rows in this data table.

Arguments

time_created
UNIX timestamp, optional

Filter data rows by the time they were created

Allowed Modifiers: time_created[min], time_created[max] (?)
contact_id
string ID of Contact, optional

Filter data rows associated with a particular contact

vars
object, optional

Filter data rows by value of a custom variable (e.g. vars[q1], vars[foo], etc.)

Allowed Modifiers: vars[foo][ne], vars[foo][prefix], vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte], vars[foo][min], vars[foo][max], vars[foo][exists] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of DataRow

Raw API: Query result of DataRow

Permission Required

View data tables

Example

Add new data row

POST /v1/projects/<project_id>/tables/<table_id>/rows

Adds a new row to this data table.

Arguments

contact_id
string ID of Contact, optional

ID of the contact that this row is associated with (if applicable)

from_number
string, optional

Phone number that this row is associated with (if applicable)

vars
string, optional

Custom variables and values to set for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

DataRow

Permission Required

Edit data tables

Example

Update data row

POST /v1/projects/<project_id>/tables/<table_id>/rows/<row_id>

Updates writable fields on the given data data row.

Arguments

contact_id
string ID of Contact, optional

ID of the contact this row is associated with (or null if not associated with any contact)

from_number
string, optional

Phone number that this row is associated with (or null if not associated with any phone number)

vars
object, optional

Custom variables stored for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: DataRow

Permission Required

Edit data tables

Example

Delete data row

DELETE /v1/projects/<project_id>/tables/<table_id>/rows/<row_id>

Deletes this data row.

Arguments

None

Return Type

undefined

Permission Required

Edit data tables

Example

Get data row by ID

GET /v1/projects/<project_id>/tables/<table_id>/rows/<row_id>

Retrieves the row in the given table with the given ID.

Arguments

None

Return Type

DataRow

Permission Required

View data tables

Example

Get fields in data table

GET /v1/projects/<project_id>/tables/<table_id>/fields

Gets a list of all fields (columns) defined for this data table. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and 'lookup_key'. (Fields are automatically created any time a DataRow's 'vars' property is updated.)

Arguments

None

Return Type

array

Permission Required

View data tables

Example

Update field metadata

POST /v1/projects/<project_id>/tables/<table_id>/fields/<variable>

Allows customizing how a field (column) is displayed in the Telerivet web app.

The variable path parameter can contain the characters a-z, A-Z, 0-9, and _, and may be up to 32 characters in length.

Arguments

name
string, max 64 characters, optional

Display name for the field

type
string, optional

Field type

Possible Values: text, long_text, secret, phone_number, email, url, audio, date, date_time, number, boolean, checkbox, select, radio, route
order
int, optional

Order in which to display the field

items
array, required if type is `select`

Array of up to 100 objects containing value and label string properties to show in the dropdown list when type is select. Each value and label must be between 1 and 256 characters in length.

readonly
bool, optional

Set to true to prevent editing the field in the Telerivet web app

lookup_key
bool, optional

Set to true to allow using this field as a lookup key when importing rows via the Telerivet web app

Return Type

object

Permission Required

Edit data tables

Example

Count rows by value

GET /v1/projects/<project_id>/tables/<table_id>/count_rows_by_value

Returns the number of rows for each value of a given variable. This can be used to get the total number of responses for each choice in a poll, without making a separate query for each response choice. The return value is an object mapping values to row counts, e.g. {"yes":7,"no":3}

Arguments

variable
string, required

Variable of field to count by.

Return Type

object

Permission Required

View data tables

Example

Update table details

POST /v1/projects/<project_id>/tables/<table_id>

Updates writable fields on the given data table.

Arguments

name
string, optional

Name of the data table

show_add_row
bool, optional

Whether to allow adding or importing rows via the web app

show_stats
bool, optional

Whether to show summary charts (pie charts, bar charts, tables of top values) for this data table in the web app

show_contact_columns
bool, optional

Whether to show 'Contact Name' and 'Phone Number' columns in the web app

vars
object, optional

Custom variables stored for this data table. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: DataTable

Permission Required

Edit data tables

Example

Delete a data table

DELETE /v1/projects/<project_id>/tables/<table_id>

Permanently deletes the given data table, including all its rows

Arguments

None

Return Type

undefined

Permission Required

Edit data tables

Example

Query data tables

GET /v1/projects/<project_id>/tables

Queries data tables within the given project.

Arguments

name
string, optional

Filter data tables by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of DataTable

Raw API: Query result of DataTable

Permission Required

View data tables

Example

Projects

Object Type: Project

Represents a Telerivet project.

Provides methods for sending and scheduling messages, as well as accessing, creating and updating a variety of entities, including contacts, messages, scheduled messages, groups, labels, phones, services, and data tables.

Attributes

id
string, max 34 characters

ID of the project

read-only
name
string

Name of the project

updatable
timezone_id
string

Default TZ database timezone ID; see List of tz database time zones Wikipedia article.

updatable
url_slug
string

Unique string used as a component of the project's URL in the Telerivet web app

updatable
default_route_id
string

The ID of a basic route or custom route that will be used to send messages by default (via both the API and web app), unless a particular route ID is specified when sending the message.

updatable
auto_create_contacts
bool

If true, a contact will be automatically created for each unique phone number that a message is sent to or received from. If false, contacts will not automatically be created (unless contact information is modified by an automated service). The Conversations tab in the web app will only show messages that are associated with a contact.

updatable
vars
object

Custom variables stored for this project. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable
organization_id
string ID of Organization

ID of the organization this project belongs to

read-only

Example

{
 "id": "PJ2ad0100821a98bea",
 "name": "Example Project",
 "timezone_id": "America/Los_Angeles",
 "url_slug": "asdf",
 "default_route_id": null,
 "auto_create_contacts": true,
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "organization_id": "AC1230123421123123",
 "url": "https://telerivet.com/p/asdf"
}

Create a project

POST /v1/organizations/<organization_id>/projects

Creates a new project.

Some project settings are not currently possible to configure via the API, and can only be edited via the web app after the project is created.

Arguments

name
string, required

Name of the project to create, which must be unique in the organization.

timezone_id
string, optional

Default TZ database timezone ID; see List of tz database time zones Wikipedia article. This timezone is used when computing statistics by date.

url_slug
string, optional

Unique string used as a component of the project's URL in the Telerivet web app. If not provided, a URL slug will be generated automatically.

auto_create_contacts
bool, optional

If true, a contact will be automatically created for each unique phone number that a message is sent to or received from. If false, contacts will not automatically be created (unless contact information is modified by an automated service). The Conversations tab in the web app will only show messages that are associated with a contact.

Default: true
vars
string, optional

Custom variables and values to set for this project

Return Type

Project

Permission Required

Edit project settings

Example

Get project by ID

GET /v1/projects/<project_id>

Retrieves the Telerivet project with the given ID.

Arguments

None

Return Type

Project

Example

Query projects

GET /v1/projects

Queries projects accessible to the current user account.

Arguments

name
string, optional

Filter projects by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Project

Raw API: Query result of Project

Example

Get user accounts

GET /v1/projects/<project_id>/users

Returns an array of user accounts that have access to this project. Each item in the array is an object containing id, email, and name properties. (The id corresponds to the user_id property of the Message object.)

Arguments

None

Return Type

array

Permission Required

View user permissions

Example

Get message statistics

GET /v1/projects/<project_id>/message_stats

Retrieves statistics about messages sent or received via Telerivet. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone, and does not contain message statistics for the current day.

Arguments

start_date
string, required

Start date of message statistics, in YYYY-MM-DD format

end_date
string, required

End date of message statistics (inclusive), in YYYY-MM-DD format

rollup
string, optional

Date interval to group by

Possible Values: day, week, month, year, all
Default: day
properties
string, optional

Comma separated list of properties to group by

Possible Values: org_id, org_name, org_industry, project_id, project_name, user_id, user_email, user_name, phone_id, phone_name, phone_type, direction, source, status, network_code, network_name, message_type, service_id, service_name, simulated, link
metrics
string, required

Comma separated list of metrics to return (summed for each distinct value of the requested properties)

Possible Values: count, num_parts, duration, price
currency
string, optional

Three-letter ISO 4217 currency code used when returning the 'price' field. If the original price was in a different currency, it will be converted to the requested currency using the approximate current exchange rate.

Default: USD
filters
object, optional

Key-value pairs of properties and corresponding values; the returned statistics will only include messages where the property matches the provided value. Only the following properties are supported for filters: user_id, phone_id, direction, source, status, service_id, simulated, message_type, network_code

Return Type

object

Return Value Properties

intervals
array

List of objects representing each date interval containing at least one message matching the filters. Each object has the following properties:

start_time The UNIX timestamp of the start of the interval (int)
end_time The UNIX timestamp of the end of the interval, exclusive (int)
start_date The date of the start of the interval in YYYY-MM-DD format (string)
end_date The date of the end of the interval in YYYY-MM-DD format, inclusive (string)
groups Array of groups for each combination of requested property values matching the filters (array)

Each object has the following properties:
properties An object of key/value pairs for each distinct value of the requested properties (object)
metrics An object of key/value pairs for each requested metric (object)

Permission Required

View statistics

Example

Update project details

POST /v1/projects/<project_id>

Updates writable fields on the given project.

Arguments

name
string, optional

Name of the project

timezone_id
string, optional

Default TZ database timezone ID; see List of tz database time zones Wikipedia article.

url_slug
string, optional

Unique string used as a component of the project's URL in the Telerivet web app

default_route_id
string, optional

The ID of a basic route or custom route that will be used to send messages by default (via both the API and web app), unless a particular route ID is specified when sending the message.

auto_create_contacts
bool, optional

If true, a contact will be automatically created for each unique phone number that a message is sent to or received from. If false, contacts will not automatically be created (unless contact information is modified by an automated service). The Conversations tab in the web app will only show messages that are associated with a contact.

vars
object, optional

Custom variables stored for this project. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

Return Type

Client libraries: undefined

Raw API: Project

Permission Required

Edit project settings

Example

Airtime Transactions

Object Type: AirtimeTransaction

Represents a transaction where airtime is sent to a mobile phone number.

To send airtime, first create a Custom Actions service to send a particular amount of airtime, then trigger the service using service.invoke, project.sendBroadcast, or project.scheduleMessage.

Attributes

id
string

ID of the airtime transaction

read-only
to_number
string

Destination phone number in international format (no leading +)

read-only
operator_name
string

Operator name

read-only
country
string

Country code

read-only
time_created
UNIX timestamp

The time that the airtime transaction was created on Telerivet's servers

read-only
transaction_time
UNIX timestamp

The time that the airtime transaction was sent, or null if it has not been sent

read-only
status
string

Current status of airtime transaction (successful, failed, cancelled, queued, processing, submitted, pending_approval, or pending_payment)

read-only
status_text
string

Error or success message returned by airtime provider, if available

read-only
value
string

Value of airtime sent to destination phone number, in units of value_currency

read-only
value_currency
string

Currency code of price

read-only
price
string

Price charged for airtime transaction, in units of price_currency

read-only
price_currency
string

Currency code of price

read-only
contact_id
string

ID of the contact the airtime was sent to

read-only
service_id
string

ID of the service that sent the airtime

read-only
project_id
string

ID of the project that the airtime transaction belongs to

read-only
external_id
string

The ID of this transaction from an external airtime gateway provider, if available.

read-only
user_id
string, max 34 characters

ID of the Telerivet user who sent the airtime transaction (if applicable)

read-only
vars
object

Custom variables stored for this transaction. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

updatable

Example

{
 "id": "ATb11111211217d11f",
 "to_number": "639123123123",
 "operator_name": "Globe Philippines",
 "country": "PH",
 "time_created": 1390347812,
 "transaction_time": 1390347813,
 "status": "successful",
 "status_text": "Transaction successful",
 "value": 25,
 "value_currency": "PHP",
 "price": 0.63,
 "price_currency": "USD",
 "contact_id": "CTa01111211217d24e",
 "service_id": "SVb12345211217d35f",
 "project_id": "PJ012345211217c11a",
 "external_id": "GLYV2R8GHY8LS17Y0S0G",
 "user_id": "URba3e403e98f49735",
 "vars": {
  "foo": "bar",
  "baz": 42
 }
}

Query airtime transactions

GET /v1/projects/<project_id>/airtime_transactions

Returns information about each airtime transaction.

Arguments

time_created[min]
UNIX timestamp, optional

Filter transactions created on or after a particular time

time_created[max]
UNIX timestamp, optional

Filter transactions created before a particular time

contact_id
string, optional

Filter transactions sent to a particular contact

to_number
string, optional

Filter transactions sent to a particular phone number

service_id
string, optional

Filter transactions sent by a particular service

status
string, optional

Filter transactions by status

Possible Values: pending, queued, processing, submitted, successful, failed, cancelled, pending_payment, pending_approval
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of AirtimeTransaction

Raw API: Query result of AirtimeTransaction

Permission Required

View airtime

Example

Get airtime transaction by ID

GET /v1/projects/<project_id>/airtime_transactions/<airtimetransaction_id>

Gets an airtime transaction by ID

Arguments

None

Return Type

AirtimeTransaction

Permission Required

View airtime

Example

Organizations

Object Type: Organization

Represents a Telerivet organization.

Attributes

id
string, max 34 characters

ID of the organization

read-only
name
string

Name of the organization

updatable
timezone_id
string

Billing quota time zone ID; see List of tz database time zones Wikipedia article.

updatable

Example

{
 "id": "ACa073512bd217d24e",
 "name": "Example Organization",
 "timezone_id": "America/Los_Angeles"
}

Get organization by ID

GET /v1/organizations/<organization_id>

Retrieves the Telerivet organization with the given ID.

Arguments

None

Return Type

Organization

Permission Required

Access organization

Example

Query organizations

GET /v1/organizations

Queries organizations accessible to the current user account.

Arguments

name
string, optional

Filter organizations by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Organization

Raw API: Query result of Organization

Example

Update organization settings

POST /v1/organizations/<organization_id>

Saves any fields that have changed for this organization.

Arguments

name
string, optional

Name of the organization

timezone_id
string, optional

Billing quota time zone ID; see List of tz database time zones Wikipedia article.

Return Type

Client libraries: undefined

Raw API: Organization

Permission Required

Edit organization settings

Example

Get billing details

GET /v1/organizations/<organization_id>/billing

Retrieves information about the organization's service plan and account balance.

Arguments

None

Return Type

object

Return Value Properties

balance
string

Prepaid account balance

balance_currency
string

Currency of prepaid account balance

plan_name
string

Name of service plan

plan_price
string

Price of service plan

plan_currency
string

Currency of service plan price

plan_rrule
string

Service plan recurrence rule (e.g. FREQ=MONTHLY or FREQ=YEARLY)

plan_paid
boolean

true if the service plan has been paid for the current billing interval; false if it is unpaid (free plans are considered paid)

plan_start_time
UNIX timestamp

Time when the current billing interval started

plan_end_time
UNIX timestamp

Time when the current billing interval ends

plan_suspend_time
UNIX timestamp

Time when the account will be suspended, if the plan remains unpaid after plan_end_time (may be null)

plan_limits
object

Object describing the limits associated with the current service plan. The object contains the following keys: phones, projects, active_services, users, contacts, messages_day, stored_messages, data_rows, api_requests_day. The values corresponding to each key are integers, or null.

recurring_billing_enabled
boolean

True if recurring billing is enabled, false otherwise

auto_refill_enabled
boolean

True if auto-refill is enabled, false otherwise

Permission Required

View billing information

Example

Get current usage

GET /v1/organizations/<organization_id>/usage/<usage_type>

Retrieves the current usage count associated with a particular service plan limit. Available usage types are phones, projects, users, contacts, messages_day, stored_messages, data_rows, and api_requests_day.

Arguments

None

Return Type

int

Permission Required

View billing information

Example

Get message statistics for all projects in organization

GET /v1/organizations/<organization_id>/message_stats

Retrieves statistics about messages sent or received via Telerivet. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone, and does not contain message statistics for the current day.

Arguments

start_date
string, required

Start date of message statistics, in YYYY-MM-DD format

end_date
string, required

End date of message statistics (inclusive), in YYYY-MM-DD format

rollup
string, optional

Date interval to group by

Possible Values: day, week, month, year, all
Default: day
properties
string, optional

Comma separated list of properties to group by

Possible Values: org_id, org_name, org_industry, project_id, project_name, user_id, user_email, user_name, phone_id, phone_name, phone_type, direction, source, status, network_code, network_name, message_type, service_id, service_name, simulated, link
metrics
string, required

Comma separated list of metrics to return (summed for each distinct value of the requested properties)

Possible Values: count, num_parts, duration, price
currency
string, optional

Three-letter ISO 4217 currency code used when returning the 'price' field. If the original price was in a different currency, it will be converted to the requested currency using the approximate current exchange rate.

Default: USD
filters
object, optional

Key-value pairs of properties and corresponding values; the returned statistics will only include messages where the property matches the provided value. Only the following properties are supported for filters: user_id, phone_id, direction, source, status, service_id, simulated, message_type, network_code

Return Type

object

Return Value Properties

intervals
array

List of objects representing each date interval containing at least one message matching the filters. Each object has the following properties:

start_time The UNIX timestamp of the start of the interval (int)
end_time The UNIX timestamp of the end of the interval, exclusive (int)
start_date The date of the start of the interval in YYYY-MM-DD format (string)
end_date The date of the end of the interval in YYYY-MM-DD format, inclusive (string)
groups Array of groups for each combination of requested property values matching the filters (array)

Each object has the following properties:
properties An object of key/value pairs for each distinct value of the requested properties (object)
metrics An object of key/value pairs for each requested metric (object)

Permission Required

View statistics

Example

Query projects in organization

GET /v1/organizations/<organization_id>/projects

Queries projects in this organization.

Arguments

name
string, optional

Filter projects by name

Allowed Modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt], name[lt], name[lte] (?)
sort
string, optional

Sort the results based on a field

Possible Values: default, name
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Project

Raw API: Query result of Project

Permission Required

View projects

Example

Batch Tasks

Object Type: Task

Represents an asynchronous task that is applied to all entities matching a filter.

Tasks include services applied to contacts, messages, or data rows; adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV.

Attributes

id
string, max 34 characters

ID of the task

read-only
task_type
string

The task type

read-only
task_params
object

Parameters applied to all matching rows (specific to task_type). See project.createTask.

read-only
filter_type
string

Type of filter defining the rows that the task is applied to

read-only
filter_params
object

Parameters defining the rows that the task is applied to (specific to filter_type). See project.createTask.

read-only
time_created
UNIX timestamp

Time the task was created in Telerivet

read-only
time_active
UNIX timestamp

Time Telerivet started executing the task

read-only
time_complete
UNIX timestamp

Time Telerivet finished executing the task

read-only
total_rows
int

The total number of rows matching the filter (null if not known)

read-only
current_row
int

The number of rows that have been processed so far

read-only
status
string

The current status of the task

Possible Values: created, queued, active, complete, failed, cancelled
read-only
vars
object

Custom variables stored for this task. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

read-only
table_id
string ID of DataTable

ID of the data table this task is applied to (if applicable)

read-only
user_id
string, max 34 characters

ID of the Telerivet user who created the task (if applicable)

read-only
project_id
string ID of Project

ID of the project this task belongs to

read-only

Example

{
 "id": "DE1189812e59c5c781",
 "task_type": "add_group_members",
 "task_params": {
  "group_id": "CG1123812e59c5c456"
 },
 "filter_type": "query_contacts",
 "filter_params": {
  "last_message_time": {
   "min": 1615334071
  }
 },
 "time_created": 1390348075,
 "time_active": 1390348076,
 "time_complete": null,
 "total_rows": 12000,
 "current_row": 3000,
 "status": "active",
 "vars": {
  "foo": "bar",
  "baz": 42
 },
 "table_id": null,
 "user_id": "URba3e403e98f49735",
 "project_id": "PJ2ad0100821a98bea"
}

Create a task

POST /v1/projects/<project_id>/tasks

Creates and starts an asynchronous task that is applied to all entities matching a filter (e.g. contacts, messages, or data rows). Tasks are designed to efficiently process a large number of entities. When processing a large number of entities, tasks are much faster than using the API to query and loop over all objects matching a filter.

Several different types of tasks are supported, including applying services to contacts, messages, or data rows; adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV.

When using a task to apply a Custom Actions or Cloud Script API service (apply_service_to_contacts, apply_service_to_rows, or apply_service_to_messages), the task variable will be available within the service. The service can use custom variables on the task object (e.g. task.vars.example), such as to store aggregate statistics for the rows matching the filter.

Arguments

task_type
string, required

Type of task to create. Each task_type applies to a certain type of entity (such as a contact, message, or data row).

Tasks for contacts:

  • update_contact_var
  • add_group_members
  • remove_group_members
  • set_conversation_status
  • set_send_blocked
  • apply_service_to_contacts
  • delete_contacts
  • export_contacts

Tasks for data rows:

  • update_row_var
  • apply_service_to_rows
  • delete_rows
  • export_rows

Tasks for messages:

  • cancel_messages
  • resend_messages
  • retry_message_services
  • apply_service_to_messages
  • add_label
  • remove_label
  • update_message_var
  • delete_messages
  • export_messages
task_params
object, optional

Parameters applied to all matching rows (specific to task_type).

apply_service_to_contacts, apply_service_to_messages, apply_service_to_rows:

service_id The ID of the service to apply (string)
variables Optional object containing up to 25 temporary variable names and their corresponding values to set when invoking the service. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Within Custom Actions, each variable can be used like [[$name]] (with a leading $ character and surrounded by double square brackets). Within a Cloud Script API service or JavaScript action, each variable will be available as a global JavaScript variable like $name (with a leading $ character). (object)


update_contact_var, update_message_var, update_row_var:

variable The custom variable name (string)
value The value to set (string, boolean, float, null)


add_group_members, remove_group_members:

group_id The ID of the group (string)


add_label, remove_label:

label_id The ID of the label (string)


resend_messages:

route_id ID of the new route to use, or null to use the original route (string)


set_send_blocked:

send_blocked true to block sending messages, false to unblock sending messages (boolean)


set_conversation_status:

conversation_status "active", "handled", or "closed" (string)


export_contacts, export_messages, export_rows:

storage_id ID of a storage provider where the CSV file will be saved. (string) Currently only AWS S3 is supported as a storage provider. This requires creating a S3 bucket in your own AWS account, as well as an IAM user with access key and secret that has permission to write to that bucket. You can configure your own S3 bucket as a storage provider on the Storage Providers page. Direct downloads are not supported when exporting data via the API. (string)
filename Path within the storage backend where the CSV file will be saved
column_ids IDs of columns to save in the CSV file. If not provided, all default columns will be saved. (array of strings, optional)


delete_contacts, delete_messages, delete_rows, cancel_messages, retry_message_services:
No parameters.

filter_type
string, required

Type of filter defining the rows that the task is applied to.

Each filter_type queries a certain type of entity (such as contacts, messages, or data rows).

In general, the task_type and the filter_type must return the same type of entity; however, tasks applied to contacts (other than export_contacts) can also be applied when the filter returns entities that are associated with a contact, such as messages or data rows. (Note that in this case, it is possible for the task to be applied multiple times to an individual contact if multiple messages or data rows are associated with the same contact.)

Possible Values: query_contacts, contact_ids, query_rows, row_ids, query_messages, message_ids
filter_params
object, required

Parameters defining the rows that the task is applied to (specific to filter_type).

query_contacts:
The same filter parameters as used by project.queryContacts. If you want to apply the task to all contacts, use the parameters {"all": true}.

contact_ids:

`contact_ids` IDs of up to 100 contacts to apply this task to (array of strings)

query_messages:
The same filter parameters as used by project.queryMessages. If you want to apply the task to all messages, use the parameters {"all": true}.

message_ids:

`message_ids` IDs of up to 100 messages to apply this task to (array of strings)

query_rows:
The same filter parameters as used by table.queryRows. If you want to apply the task to all rows in the table, use the parameters {"all": true}.

row_ids:

`row_ids` IDs of up to 100 data rows to apply this task to (array of strings)
table_id
string ID of DataTable, optional

ID of the data table this task is applied to (if applicable).

Required if filter_type is query_rows or row_ids.

vars
object, optional

Initial custom variables to set for the task.

If the task applies a service, the service can read and write custom variables on the task object (e.g. task.vars.example), such as to store aggregate statistics for the rows matching the filter.

Return Type

Task

Permission Required

View automated services

Example

Cancel a task

POST /v1/projects/<project_id>/tasks/<task_id>/cancel

Cancels a task that is not yet complete.

Arguments

None

Return Type

Task

Permission Required

Edit data tables

Example

Query tasks

GET /v1/projects/<project_id>/tasks

Queries batch tasks within the given project.

Arguments

sort
string, optional

Sort the results based on a field

Possible Values: default
Default: default
sort_dir
string, optional

Sort the results in ascending or descending order

Possible Values: asc, desc
Default: asc
page_size
int, optional

Number of results returned per page (max 500)

Default: 50
offset
int, optional

Number of items to skip from beginning of result set

Default: 0
marker
string, optional

'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start.

count
bool, optional

If true, the API will return the count of items matching the filter, instead of the items themselves

Default: false

Return Type

Client libraries: APICursor of Task

Raw API: Query result of Task

Permission Required

View automated services

Example

Get task by ID

GET /v1/projects/<project_id>/tasks/<task_id>

Retrieves the task with the given ID.

Arguments

None

Return Type

Task

Permission Required

View automated services

Example

Variable Reference

The REST API makes it easy to "mail-merge" with Telerivet's contact database when sending messages.

To insert a variable in your message content, surround the variable name in double square brackets (for example, [[contact.name]]), and make sure to set the replace_variables parameter to 1.

The variables available when sending a message are listed below:

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