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:
curl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/send" \
-H "Content-Type: application/json" \
-d '{
"content": "hello world",
"to_number": "+16505550123"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$sent_msg = $project->sendMessage([
'content' => "hello world",
'to_number' => "+16505550123"
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
sent_msg = project.sendMessage(
content = "hello world",
to_number = "+16505550123"
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
sent_msg = project.send_message({
'content' => "hello world",
'to_number' => "+16505550123"
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.sendMessage({
content: "hello world",
to_number: "+16505550123"
}, function(err, message) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message sent_msg = project.sendMessage(Util.options(
"content", "hello world",
"to_number", "+16505550123"
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message sent_msg = await project.SendMessageAsync(Util.Options(
"content", "hello world",
"to_number", "+16505550123"
));
To run the example code, you'll need to
install the PHP client library and
install the Python client library and
install the Ruby client library and
install the Node.js client library and
install the .NET client library and
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
curl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "John Smith",
"phone_number": "+16505550123",
"send_blocked": false,
"conversation_status": "active",
"vars": {
"email": "jsmith@example.com",
"birthdate": "1953-01-05"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$contact->name = "John Smith";
$contact->phone_number = "+16505550123";
$contact->send_blocked = false;
$contact->conversation_status = "active";
$contact->vars->email = "jsmith@example.com";
$contact->vars->birthdate = "1953-01-05";
$contact->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
contact.name = "John Smith"
contact.phone_number = "+16505550123"
contact.send_blocked = False
contact.conversation_status = "active"
contact.vars.email = "jsmith@example.com"
contact.vars.birthdate = "1953-01-05"
contact.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
contact.name = "John Smith"
contact.phone_number = "+16505550123"
contact.send_blocked = false
contact.conversation_status = "active"
contact.vars.email = "jsmith@example.com"
contact.vars.birthdate = "1953-01-05"
contact.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
contact.name = "John Smith";
contact.phone_number = "+16505550123";
contact.send_blocked = false;
contact.conversation_status = "active";
contact.vars.email = "jsmith@example.com";
contact.vars.birthdate = "1953-01-05";
contact.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
contact.setName("John Smith");
contact.setPhoneNumber("+16505550123");
contact.setSendBlocked(false);
contact.setConversationStatus("active");
contact.vars().set("email", "jsmith@example.com");
contact.vars().set("birthdate", "1953-01-05");
contact.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
contact.Name = "John Smith";
contact.PhoneNumber = "+16505550123";
contact.SendBlocked = false;
contact.ConversationStatus = "active";
contact.Vars.Set("email", "jsmith@example.com");
contact.Vars.Set("birthdate", "1953-01-05");
await contact.SaveAsync();
|
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
curl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->getContactById($contact_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.getContactById(contact_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.get_contact_by_id(contact_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getContactById(contact_id, function(err, contact) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.getContactById(contact_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = await project.GetContactByIdAsync(contact_id);
|
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
curl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts" \
-H "Content-Type: application/json" \
-d '{
"name": "John Smith",
"phone_number": "5550123",
"add_group_ids": [
"CG37f46ac132ef1542",
"CG47f46ac232ee0123"
],
"vars": {
"email": "jsmith@example.com",
"birthdate": "1953-01-04",
"your_id": "12942938"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->getOrCreateContact([
'name' => "John Smith",
'phone_number' => "5550123",
'add_group_ids' => ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
'vars' => ['email' => "jsmith@example.com", 'birthdate' => "1953-01-04", 'your_id' => "12942938"]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.getOrCreateContact(
name = "John Smith",
phone_number = "5550123",
add_group_ids = ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
vars = {'email': "jsmith@example.com", 'birthdate': "1953-01-04", 'your_id': "12942938"}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.get_or_create_contact({
'name' => "John Smith",
'phone_number' => "5550123",
'add_group_ids' => ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
'vars' => {'email' => "jsmith@example.com", 'birthdate' => "1953-01-04", 'your_id' => "12942938"}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getOrCreateContact({
name: "John Smith",
phone_number: "5550123",
add_group_ids: ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
vars: {'email': "jsmith@example.com", 'birthdate': "1953-01-04", 'your_id': "12942938"}
}, function(err, contact) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.getOrCreateContact(Util.options(
"name", "John Smith",
"phone_number", "5550123",
"add_group_ids", new Object[] {"CG37f46ac132ef1542", "CG47f46ac232ee0123"},
"vars", Util.options("email", "jsmith@example.com", "birthdate", "1953-01-04", "your_id", "12942938")
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = await project.GetOrCreateContactAsync(Util.Options(
"name", "John Smith",
"phone_number", "5550123",
"add_group_ids", new Object[] {"CG37f46ac132ef1542", "CG47f46ac232ee0123"},
"vars", Util.Options("email", "jsmith@example.com", "birthdate", "1953-01-04", "your_id", "12942938")
));
|
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
curl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts?sort=name&sort_dir=desc&offset=50"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryContacts([
'sort' => "name",
'sort_dir' => "desc",
'offset' => 50
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$contact = $cursor->next();
// do something with $contact
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryContacts(
sort = "name",
sort_dir = "desc",
offset = 50
)
for contact in cursor.limit(50):
# do something with contact
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_contacts({
'sort' => "name",
'sort_dir' => "desc",
'offset' => 50
})
cursor.limit(50).each { |contact|
# do something with contact
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryContacts({
sort: "name",
sort_dir: "desc",
offset: 50
});
cursor.limit(50).each(function(err, contact) {
if (err) {
// do something with err
}
if (contact) {
// do something with contact
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Contact> cursor = project.queryContacts(Util.options(
"sort", "name",
"sort_dir", "desc",
"offset", 50
));
cursor.limit(50);
while (cursor.hasNext()) {
Contact contact = cursor.next();
// do something with contact
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Contact> cursor = project.QueryContacts(Util.Options(
"sort", "name",
"sort_dir", "desc",
"offset", 50
));
List<Contact> list = await query.Limit(50).AllAsync();
foreach (Contact contact in list) {
// do something with contact
}
|
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
prefix | Filter objects where the field starts with the parameter value (case-insensitive). Only applicable for string fields. |
not_prefix | Filter objects where the field does not start with the parameter value (case-insensitive). Only applicable for string fields. |
exists | If 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. |
null | If 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. |
gte | Filter 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. |
gt | Filter 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. |
lt | Filter 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. |
lte | Filter 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. |
min | Filter objects where the value is greater than or equal to the parameter value (inclusive), always performing a numeric comparison. Not applicable for string fields. |
max | Filter objects where the value is less than the parameter value (non-inclusive), always performing a numeric comparison. Not applicable for string fields. |
ne | Filter objects where the field does not match the parameter value exactly (case-insensitive). |
eq | Filter objects where the field matches the parameter value exactly (case-insensitive). This is the same as not using any modifier. |
|
Example
curl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts?name[prefix]=John&last_message_time[min]=1733350916"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryContacts([
'sort' => "name",
'sort_dir' => "desc",
'offset' => 50
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$contact = $cursor->next();
// do something with $contact
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryContacts(
sort = "name",
sort_dir = "desc",
offset = 50
)
for contact in cursor.limit(50):
# do something with contact
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_contacts({
'sort' => "name",
'sort_dir' => "desc",
'offset' => 50
})
cursor.limit(50).each { |contact|
# do something with contact
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryContacts({
sort: "name",
sort_dir: "desc",
offset: 50
});
cursor.limit(50).each(function(err, contact) {
if (err) {
// do something with err
}
if (contact) {
// do something with contact
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Contact> cursor = project.queryContacts(Util.options(
"sort", "name",
"sort_dir", "desc",
"offset", 50
));
cursor.limit(50);
while (cursor.hasNext()) {
Contact contact = cursor.next();
// do something with contact
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Contact> cursor = project.QueryContacts(Util.Options(
"sort", "name",
"sort_dir", "desc",
"offset", 50
));
List<Contact> list = await query.Limit(50).AllAsync();
foreach (Contact contact in list) {
// do something with contact
}
|
Messages | |
Object Type: Message
Represents a single message.
Attributesid |
string, max 34 characters | 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 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 LabelList 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 |
ID of the service that handled the message (for voice calls, the service defines the call flow)
| read-only |
phone_id |
ID of the phone (basic route) that sent or received the message
| read-only |
contact_id |
ID of the contact that sent or received the message
| read-only |
route_id |
ID of the custom route that sent the message (if applicable)
| read-only |
broadcast_id |
ID of the broadcast that this message is part of (if applicable)
| read-only |
scheduled_id |
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 |
ID of the project this contact belongs to
| read-only |
|
ExampleTelerivet_Message JSON: Message JSON: Telerivet::Message JSON: Message JSON: Message JSON: Message JSON: {
"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.
Attributesid |
string, max 34 characters | 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 LabelList 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 |
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 |
ID of the project this broadcast belongs to
| read-only |
|
ExampleTelerivet_Broadcast JSON: Broadcast JSON: Telerivet::Broadcast JSON: Broadcast JSON: Broadcast JSON: Broadcast JSON: {
"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
Argumentsmessage_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 | 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 TypeMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/send" \
-H "Content-Type: application/json" \
-d '{
"content": "hello world",
"to_number": "+16505550123"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$sent_msg = $project->sendMessage([
'content' => "hello world",
'to_number' => "+16505550123"
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
sent_msg = project.sendMessage(
content = "hello world",
to_number = "+16505550123"
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
sent_msg = project.send_message({
'content' => "hello world",
'to_number' => "+16505550123"
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.sendMessage({
content: "hello world",
to_number: "+16505550123"
}, function(err, message) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message sent_msg = project.sendMessage(Util.options(
"content", "hello world",
"to_number", "+16505550123"
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message sent_msg = await project.SendMessageAsync(Util.Options(
"content", "hello world",
"to_number", "+16505550123"
));
|
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.
Argumentsmessage_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 TypeBroadcast Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/send_broadcast" \
-H "Content-Type: application/json" \
-d '{
"content": "hello [[contact.name]]!",
"to_numbers": [
"+14155550123",
"+14255550234",
"+16505550345"
],
"status_url": "https://example.com/sms_status.php",
"status_secret": "t0psecr3t",
"replace_variables": true
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$broadcast = $project->sendBroadcast([
'content' => "hello [[contact.name]]!",
'to_numbers' => ["+14155550123", "+14255550234", "+16505550345"],
'status_url' => "https://example.com/sms_status.php",
'status_secret' => "t0psecr3t",
'replace_variables' => true
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
broadcast = project.sendBroadcast(
content = "hello [[contact.name]]!",
to_numbers = ["+14155550123", "+14255550234", "+16505550345"],
status_url = "https://example.com/sms_status.php",
status_secret = "t0psecr3t",
replace_variables = True
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
broadcast = project.send_broadcast({
'content' => "hello [[contact.name]]!",
'to_numbers' => ["+14155550123", "+14255550234", "+16505550345"],
'status_url' => "https://example.com/sms_status.php",
'status_secret' => "t0psecr3t",
'replace_variables' => true
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.sendBroadcast({
content: "hello [[contact.name]]!",
to_numbers: ["+14155550123", "+14255550234", "+16505550345"],
status_url: "https://example.com/sms_status.php",
status_secret: "t0psecr3t",
replace_variables: true
}, function(err, broadcast) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Broadcast;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Broadcast broadcast = project.sendBroadcast(Util.options(
"content", "hello [[contact.name]]!",
"to_numbers", new Object[] {"+14155550123", "+14255550234", "+16505550345"},
"status_url", "https://example.com/sms_status.php",
"status_secret", "t0psecr3t",
"replace_variables", true
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Broadcast broadcast = await project.SendBroadcastAsync(Util.Options(
"content", "hello [[contact.name]]!",
"to_numbers", new Object[] {"+14155550123", "+14255550234", "+16505550345"},
"status_url", "https://example.com/sms_status.php",
"status_secret", "t0psecr3t",
"replace_variables", true
));
|
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.
Argumentsmessages | 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 | 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 Typeobject Return Value Propertiesmessages |
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 RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/send_multi" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"content": "example 1",
"to_number": "+16505550123"
},
{
"content": "example 2",
"to_number": "+16505550124"
}
],
"broadcast_title": "API Broadcast",
"status_url": "https://example.com/sms_status.php",
"status_secret": "t0psecr3t",
"replace_variables": true
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->sendMulti([
'messages' => [['content' => "example 1", 'to_number' => "+16505550123"], ['content' => "example 2", 'to_number' => "+16505550124"]],
'broadcast_title' => "API Broadcast",
'status_url' => "https://example.com/sms_status.php",
'status_secret' => "t0psecr3t",
'replace_variables' => true
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.sendMulti(
messages = [{'content': "example 1", 'to_number': "+16505550123"}, {'content': "example 2", 'to_number': "+16505550124"}],
broadcast_title = "API Broadcast",
status_url = "https://example.com/sms_status.php",
status_secret = "t0psecr3t",
replace_variables = True
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.send_multi({
'messages' => [{'content' => "example 1", 'to_number' => "+16505550123"}, {'content' => "example 2", 'to_number' => "+16505550124"}],
'broadcast_title' => "API Broadcast",
'status_url' => "https://example.com/sms_status.php",
'status_secret' => "t0psecr3t",
'replace_variables' => true
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.sendMulti({
messages: [{'content': "example 1", 'to_number': "+16505550123"}, {'content': "example 2", 'to_number': "+16505550124"}],
broadcast_title: "API Broadcast",
status_url: "https://example.com/sms_status.php",
status_secret: "t0psecr3t",
replace_variables: true
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.sendMulti(Util.options(
"messages", new Object[] {Util.options("content", "example 1", "to_number", "+16505550123"), Util.options("content", "example 2", "to_number", "+16505550124")},
"broadcast_title", "API Broadcast",
"status_url", "https://example.com/sms_status.php",
"status_secret", "t0psecr3t",
"replace_variables", true
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.SendMultiAsync(Util.Options(
"messages", new Object[] {Util.Options("content", "example 1", "to_number", "+16505550123"), Util.Options("content", "example 2", "to_number", "+16505550124")},
"broadcast_title", "API Broadcast",
"status_url", "https://example.com/sms_status.php",
"status_secret", "t0psecr3t",
"replace_variables", true
));
|
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.
Argumentslabel_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 | 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 | ID of the broadcast containing the message
Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?) | scheduled_id | 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 TypeRaw API: Query result of Message Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages?direction=incoming&message_type=sms"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryMessages([
'direction' => "incoming",
'message_type' => "sms"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$message = $cursor->next();
// do something with $message
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryMessages(
direction = "incoming",
message_type = "sms"
)
for message in cursor.limit(50):
# do something with message
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_messages({
'direction' => "incoming",
'message_type' => "sms"
})
cursor.limit(50).each { |message|
# do something with message
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryMessages({
direction: "incoming",
message_type: "sms"
});
cursor.limit(50).each(function(err, message) {
if (err) {
// do something with err
}
if (message) {
// do something with message
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Message> cursor = project.queryMessages(Util.options(
"direction", "incoming",
"message_type", "sms"
));
cursor.limit(50);
while (cursor.hasNext()) {
Message message = cursor.next();
// do something with message
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Message> cursor = project.QueryMessages(Util.Options(
"direction", "incoming",
"message_type", "sms"
));
List<Message> list = await query.Limit(50).AllAsync();
foreach (Message message in list) {
// do something with message
}
|
Remove a label from a message
DELETE /v1/projects/<project_id>/labels/<label_id>/messages/<message_id> Removes a label from the given message.
ArgumentsNone Return Typeundefined Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels/LABEL_ID/messages/MESSAGE_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->initMessageById($message_id);
$label = $project->initLabelById($label_id);
$message->removeLabel($label);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.initMessageById(message_id)
label = project.initLabelById(label_id)
message.removeLabel(label)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.init_message_by_id(message_id)
label = project.init_label_by_id(label_id)
message.remove_label(label)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var message = project.initMessageById(message_id);
var label = project.initLabelById(label_id);
message.removeLabel(label, function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.initMessageById(message_id);
Label label = project.initLabelById(label_id);
message.removeLabel(label);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = project.InitMessageById(message_id);
Label label = project.InitLabelById(label_id);
await message.RemoveLabelAsync(label);
|
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.
Argumentscontent | string, required unless `message_type` is `call` Content of the incoming message
| message_type | string, optional 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 TypeMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/receive" \
-H "Content-Type: application/json" \
-d '{
"content": "help",
"message_type": "sms",
"from_number": "+16505550193",
"to_number": "+16505551212"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->receiveMessage([
'content' => "help",
'message_type' => "sms",
'from_number' => "+16505550193",
'to_number' => "+16505551212"
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.receiveMessage(
content = "help",
message_type = "sms",
from_number = "+16505550193",
to_number = "+16505551212"
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.receive_message({
'content' => "help",
'message_type' => "sms",
'from_number' => "+16505550193",
'to_number' => "+16505551212"
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.receiveMessage({
content: "help",
message_type: "sms",
from_number: "+16505550193",
to_number: "+16505551212"
}, function(err, message) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.receiveMessage(Util.options(
"content", "help",
"message_type", "sms",
"from_number", "+16505550193",
"to_number", "+16505551212"
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = await project.ReceiveMessageAsync(Util.Options(
"content", "help",
"message_type", "sms",
"from_number", "+16505550193",
"to_number", "+16505551212"
));
|
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.)
ArgumentsNone Return Typearray Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/message_fields"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->getMessageFields();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.getMessageFields()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.get_message_fields()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getMessageFields(function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.getMessageFields();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.GetMessageFieldsAsync();
|
Get broadcast by ID
GET /v1/projects/<project_id>/broadcasts/<broadcast_id> Retrieves the broadcast with the given ID.
ArgumentsNone Return TypeBroadcast Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/broadcasts/BROADCAST_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$broadcast = $project->getBroadcastById($broadcast_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
broadcast = project.getBroadcastById(broadcast_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
broadcast = project.get_broadcast_by_id(broadcast_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getBroadcastById(broadcast_id, function(err, broadcast) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Broadcast;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Broadcast broadcast = project.getBroadcastById(broadcast_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Broadcast broadcast = await project.GetBroadcastByIdAsync(broadcast_id);
|
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.
Argumentstime_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 TypeRaw API: Query result of Broadcast Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/broadcasts"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryBroadcasts();
$cursor->limit(50);
while ($cursor->hasNext()) {
$broadcast = $cursor->next();
// do something with $broadcast
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryBroadcasts()
for broadcast in cursor.limit(50):
# do something with broadcast
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_broadcasts()
cursor.limit(50).each { |broadcast|
# do something with broadcast
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryBroadcasts();
cursor.limit(50).each(function(err, broadcast) {
if (err) {
// do something with err
}
if (broadcast) {
// do something with broadcast
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Broadcast> cursor = project.queryBroadcasts();
cursor.limit(50);
while (cursor.hasNext()) {
Broadcast broadcast = cursor.next();
// do something with broadcast
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Broadcast> cursor = project.QueryBroadcasts();
List<Broadcast> list = await query.Limit(50).AllAsync();
foreach (Broadcast broadcast in list) {
// do something with broadcast
}
|
Get message by ID
GET /v1/projects/<project_id>/messages/<message_id> Retrieves the message with the given ID.
ArgumentsNone Return TypeMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/MESSAGE_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->getMessageById($message_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.getMessageById(message_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.get_message_by_id(message_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getMessageById(message_id, function(err, message) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.getMessageById(message_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = await project.GetMessageByIdAsync(message_id);
|
Add a label to a message
PUT /v1/projects/<project_id>/labels/<label_id>/messages/<message_id> Adds a label to the given message.
ArgumentsNone Return Typeundefined Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels/LABEL_ID/messages/MESSAGE_ID" \
-X PUT
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->initMessageById($message_id);
$label = $project->initLabelById($label_id);
$message->addLabel($label);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.initMessageById(message_id)
label = project.initLabelById(label_id)
message.addLabel(label)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.init_message_by_id(message_id)
label = project.init_label_by_id(label_id)
message.add_label(label)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var message = project.initMessageById(message_id);
var label = project.initLabelById(label_id);
message.addLabel(label, function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.initMessageById(message_id);
Label label = project.initLabelById(label_id);
message.addLabel(label);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = project.InitMessageById(message_id);
Label label = project.InitLabelById(label_id);
await message.AddLabelAsync(label);
|
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).
ArgumentsNone Return TypeBroadcast Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/broadcasts/BROADCAST_ID/cancel" \
-H "Content-Type: application/json" \
-d '{ }'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$broadcast = $project->initBroadcastById($broadcast_id);
$broadcast = $broadcast->cancel();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
broadcast = project.initBroadcastById(broadcast_id)
broadcast = broadcast.cancel()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
broadcast = project.init_broadcast_by_id(broadcast_id)
broadcast = broadcast.cancel()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var broadcast = project.initBroadcastById(broadcast_id);
broadcast.cancel(function(err, broadcast) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Broadcast;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Broadcast broadcast = project.initBroadcastById(broadcast_id);
Broadcast broadcast = broadcast.cancel();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Broadcast broadcast = project.InitBroadcastById(broadcast_id);
Broadcast broadcast = await broadcast.CancelAsync();
|
Delete a message
DELETE /v1/projects/<project_id>/messages/<message_id> ArgumentsNone Return Typeundefined Permission RequiredDelete messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/MESSAGE_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->initMessageById($message_id);
$message->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.initMessageById(message_id)
message.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.init_message_by_id(message_id)
message.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var message = project.initMessageById(message_id);
message.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.initMessageById(message_id);
message.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = project.InitMessageById(message_id);
await message.DeleteAsync();
|
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'.
ArgumentsNone Return TypeMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/MESSAGE_ID/cancel" \
-H "Content-Type: application/json" \
-d '{ }'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->initMessageById($message_id);
$message = $message->cancel();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.initMessageById(message_id)
message = message.cancel()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.init_message_by_id(message_id)
message = message.cancel()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var message = project.initMessageById(message_id);
message.cancel(function(err, message) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.initMessageById(message_id);
Message message = message.cancel();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = project.InitMessageById(message_id);
Message message = await message.CancelAsync();
|
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.
Argumentsroute_id | string, optional ID of the phone or route to send the message from
|
Return TypeMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/MESSAGE_ID/resend" \
-H "Content-Type: application/json" \
-d '{
"route_id": "PN4d246818d0ecd1fa"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->initMessageById($message_id);
$message = $message->resend([
'route_id' => "PN4d246818d0ecd1fa"
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.initMessageById(message_id)
message = message.resend(
route_id = "PN4d246818d0ecd1fa"
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.init_message_by_id(message_id)
message = message.resend({
'route_id' => "PN4d246818d0ecd1fa"
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var message = project.initMessageById(message_id);
message.resend({
route_id: "PN4d246818d0ecd1fa"
}, function(err, message) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.initMessageById(message_id);
Message message = message.resend(Util.options(
"route_id", "PN4d246818d0ecd1fa"
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = project.InitMessageById(message_id);
Message message = await message.ResendAsync(Util.Options(
"route_id", "PN4d246818d0ecd1fa"
));
|
Update message details
POST /v1/projects/<project_id>/messages/<message_id> Updates writable fields on the given message
Argumentsstarred | 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 TypeClient libraries: undefined Raw API: Message Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/messages/MESSAGE_ID" \
-H "Content-Type: application/json" \
-d '{
"starred": true,
"vars": {
"foo": "bar",
"baz": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$message = $project->initMessageById($message_id);
$message->starred = true;
$message->vars->foo = "bar";
$message->vars->baz = 42;
$message->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
message = project.initMessageById(message_id)
message.starred = True
message.vars.foo = "bar"
message.vars.baz = 42
message.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
message = project.init_message_by_id(message_id)
message.starred = true
message.vars.foo = "bar"
message.vars.baz = 42
message.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var message = project.initMessageById(message_id);
message.starred = true;
message.vars.foo = "bar";
message.vars.baz = 42;
message.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Message;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Message message = project.initMessageById(message_id);
message.setStarred(true);
message.vars().set("foo", "bar");
message.vars().set("baz", 42);
message.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Message message = project.InitMessageById(message_id);
message.Starred = true;
message.Vars.Set("foo", "bar");
message.Vars.Set("baz", 42);
await message.SaveAsync();
|
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.
Argumentsname | string, max 64 characters, optional Display name for the field
| type | string, optional 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 Typeobject Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/message_fields/VARIABLE" \
-H "Content-Type: application/json" \
-d '{
"name": "Intent",
"type": "number",
"order": 2
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->setMessageFieldMetadata("intent", [
'name' => "Intent",
'type' => "number",
'order' => 2
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.setMessageFieldMetadata("intent",
name = "Intent",
type = "number",
order = 2
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.set_message_field_metadata("intent", {
'name' => "Intent",
'type' => "number",
'order' => 2
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.setMessageFieldMetadata("intent", {
name: "Intent",
type: "number",
order: 2
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.setMessageFieldMetadata("intent", Util.options(
"name", "Intent",
"type", "number",
"order", 2
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.SetMessageFieldMetadataAsync("intent", Util.Options(
"name", "Intent",
"type", "number",
"order", 2
));
|
Scheduled Messages | |
Object Type: ScheduledMessage
Represents a scheduled message within Telerivet.
Attributesid |
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 | 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 |
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 |
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 |
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 LabelIDs 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 |
|
ExampleTelerivet_ScheduledMessage JSON: ScheduledMessage JSON: Telerivet::ScheduledMessage JSON: ScheduledMessage JSON: ScheduledMessage JSON: ScheduledMessage JSON: {
"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.
Attributesid |
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 | updatable |
recipients_str |
string A string with a human readable description of the recipient
| read-only |
group_id |
ID of the group to send the message to (null if the recipient is an individual contact)
| updatable |
contact_id |
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 |
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 LabelIDs of labels to add to the Message
| updatable |
project_id |
string ID of the project this relative scheduled message belongs to
| read-only |
|
ExampleTelerivet_RelativeScheduledMessage JSON: RelativeScheduledMessage JSON: Telerivet::RelativeScheduledMessage JSON: RelativeScheduledMessage JSON: RelativeScheduledMessage JSON: RelativeScheduledMessage JSON: {
"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.
Argumentsmessage_type | string, optional 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 | 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 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 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 TypeScheduledMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/scheduled" \
-H "Content-Type: application/json" \
-d '{
"content": "Reminder!",
"to_number": "+16505550234",
"start_time_offset": 86400
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$scheduled_msg = $project->scheduleMessage([
'content' => "Reminder!",
'to_number' => "+16505550234",
'start_time_offset' => 86400
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
scheduled_msg = project.scheduleMessage(
content = "Reminder!",
to_number = "+16505550234",
start_time_offset = 86400
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
scheduled_msg = project.schedule_message({
'content' => "Reminder!",
'to_number' => "+16505550234",
'start_time_offset' => 86400
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.scheduleMessage({
content: "Reminder!",
to_number: "+16505550234",
start_time_offset: 86400
}, function(err, scheduled_msg) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.ScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
ScheduledMessage scheduled_msg = project.scheduleMessage(Util.options(
"content", "Reminder!",
"to_number", "+16505550234",
"start_time_offset", 86400
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
ScheduledMessage scheduled_msg = await project.ScheduleMessageAsync(Util.Options(
"content", "Reminder!",
"to_number", "+16505550234",
"start_time_offset", 86400
));
|
Query scheduled messages
GET /v1/projects/<project_id>/scheduled Queries scheduled messages within the given project.
Argumentsmessage_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 | 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 TypeRaw API: Query result of ScheduledMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/scheduled?message_type=sms&next_time[min]=1741126916"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryScheduledMessages([
'message_type' => "sms",
'next_time' => ['min' => 1741126916]
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$scheduled_msg = $cursor->next();
// do something with $scheduled_msg
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryScheduledMessages(
message_type = "sms",
next_time = {'min': 1741126916}
)
for scheduled_msg in cursor.limit(50):
# do something with scheduled_msg
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_scheduled_messages({
'message_type' => "sms",
'next_time' => {'min' => 1741126916}
})
cursor.limit(50).each { |scheduled_msg|
# do something with scheduled_msg
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryScheduledMessages({
message_type: "sms",
next_time: {'min': 1741126916}
});
cursor.limit(50).each(function(err, scheduled_msg) {
if (err) {
// do something with err
}
if (scheduled_msg) {
// do something with scheduled_msg
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<ScheduledMessage> cursor = project.queryScheduledMessages(Util.options(
"message_type", "sms",
"next_time", Util.options("min", 1741126916)
));
cursor.limit(50);
while (cursor.hasNext()) {
ScheduledMessage scheduled_msg = cursor.next();
// do something with scheduled_msg
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<ScheduledMessage> cursor = project.QueryScheduledMessages(Util.Options(
"message_type", "sms",
"next_time", Util.Options("min", 1741126916)
));
List<ScheduledMessage> list = await query.Limit(50).AllAsync();
foreach (ScheduledMessage scheduled_msg in list) {
// do something with scheduled_msg
}
|
Update scheduled message
POST /v1/projects/<project_id>/scheduled/<scheduled_msg_id> Updates writable fields on the given scheduled message.
Argumentscontent | 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 | 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 | 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 | 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 TypeClient libraries: undefined Raw API: ScheduledMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/scheduled/SCHEDULED_MSG_ID" \
-H "Content-Type: application/json" \
-d '{
"content": "hello world!",
"rrule": "COUNT=1",
"timezone_id": "America/Los_Angeles",
"route_id": "PN4d246818d0ecd1fa",
"service_id": "SV3d246818d0e3d1fb",
"start_time": 1395617516,
"replace_variables": false,
"vars": {
"foo": "bar",
"baz": 42
},
"label_ids": [
"LB4f3dac27154653e0"
]
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$scheduled_msg = $project->initScheduledMessageById($scheduled_msg_id);
$scheduled_msg->content = "hello world!";
$scheduled_msg->rrule = "COUNT=1";
$scheduled_msg->timezone_id = "America/Los_Angeles";
$scheduled_msg->route_id = "PN4d246818d0ecd1fa";
$scheduled_msg->service_id = "SV3d246818d0e3d1fb";
$scheduled_msg->start_time = 1395617516;
$scheduled_msg->replace_variables = false;
$scheduled_msg->vars->foo = "bar";
$scheduled_msg->vars->baz = 42;
$scheduled_msg->label_ids = ["LB4f3dac27154653e0"];
$scheduled_msg->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
scheduled_msg = project.initScheduledMessageById(scheduled_msg_id)
scheduled_msg.content = "hello world!"
scheduled_msg.rrule = "COUNT=1"
scheduled_msg.timezone_id = "America/Los_Angeles"
scheduled_msg.route_id = "PN4d246818d0ecd1fa"
scheduled_msg.service_id = "SV3d246818d0e3d1fb"
scheduled_msg.start_time = 1395617516
scheduled_msg.replace_variables = False
scheduled_msg.vars.foo = "bar"
scheduled_msg.vars.baz = 42
scheduled_msg.label_ids = ["LB4f3dac27154653e0"]
scheduled_msg.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
scheduled_msg = project.init_scheduled_message_by_id(scheduled_msg_id)
scheduled_msg.content = "hello world!"
scheduled_msg.rrule = "COUNT=1"
scheduled_msg.timezone_id = "America/Los_Angeles"
scheduled_msg.route_id = "PN4d246818d0ecd1fa"
scheduled_msg.service_id = "SV3d246818d0e3d1fb"
scheduled_msg.start_time = 1395617516
scheduled_msg.replace_variables = false
scheduled_msg.vars.foo = "bar"
scheduled_msg.vars.baz = 42
scheduled_msg.label_ids = ["LB4f3dac27154653e0"]
scheduled_msg.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var scheduled_msg = project.initScheduledMessageById(scheduled_msg_id);
scheduled_msg.content = "hello world!";
scheduled_msg.rrule = "COUNT=1";
scheduled_msg.timezone_id = "America/Los_Angeles";
scheduled_msg.route_id = "PN4d246818d0ecd1fa";
scheduled_msg.service_id = "SV3d246818d0e3d1fb";
scheduled_msg.start_time = 1395617516;
scheduled_msg.replace_variables = false;
scheduled_msg.vars.foo = "bar";
scheduled_msg.vars.baz = 42;
scheduled_msg.label_ids = ["LB4f3dac27154653e0"];
scheduled_msg.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.ScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
ScheduledMessage scheduled_msg = project.initScheduledMessageById(scheduled_msg_id);
scheduled_msg.setContent("hello world!");
scheduled_msg.setRrule("COUNT=1");
scheduled_msg.setTimezoneId("America/Los_Angeles");
scheduled_msg.setRouteId("PN4d246818d0ecd1fa");
scheduled_msg.setServiceId("SV3d246818d0e3d1fb");
scheduled_msg.setStartTime(1395617516);
scheduled_msg.setReplaceVariables(false);
scheduled_msg.vars().set("foo", "bar");
scheduled_msg.vars().set("baz", 42);
scheduled_msg.setLabelIds(new Object[] {"LB4f3dac27154653e0"});
scheduled_msg.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
ScheduledMessage scheduled_msg = project.InitScheduledMessageById(scheduled_msg_id);
scheduled_msg.Content = "hello world!";
scheduled_msg.Rrule = "COUNT=1";
scheduled_msg.TimezoneId = "America/Los_Angeles";
scheduled_msg.RouteId = "PN4d246818d0ecd1fa";
scheduled_msg.ServiceId = "SV3d246818d0e3d1fb";
scheduled_msg.StartTime = 1395617516;
scheduled_msg.ReplaceVariables = false;
scheduled_msg.Vars.Set("foo", "bar");
scheduled_msg.Vars.Set("baz", 42);
scheduled_msg.LabelIds = new Object[] {"LB4f3dac27154653e0"};
await scheduled_msg.SaveAsync();
|
Cancel a scheduled message
DELETE /v1/projects/<project_id>/scheduled/<scheduled_msg_id> Cancels this scheduled message.
ArgumentsNone Return Typeundefined Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/scheduled/SCHEDULED_MSG_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$scheduled_msg = $project->initScheduledMessageById($scheduled_msg_id);
$scheduled_msg->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
scheduled_msg = project.initScheduledMessageById(scheduled_msg_id)
scheduled_msg.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
scheduled_msg = project.init_scheduled_message_by_id(scheduled_msg_id)
scheduled_msg.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var scheduled_msg = project.initScheduledMessageById(scheduled_msg_id);
scheduled_msg.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.ScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
ScheduledMessage scheduled_msg = project.initScheduledMessageById(scheduled_msg_id);
scheduled_msg.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
ScheduledMessage scheduled_msg = project.InitScheduledMessageById(scheduled_msg_id);
await scheduled_msg.DeleteAsync();
|
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.
Argumentsmessage_type | string, optional 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 | 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 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 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 TypeRelativeScheduledMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/relative_scheduled" \
-H "Content-Type: application/json" \
-d '{
"content": "Hi [[contact.name]], just following up!",
"group_id": "GC123123123123123123",
"time_of_day": "15:07",
"date_variable": "date",
"offset_scale": "D",
"offset_count": 3,
"rrule": "FREQ=MONTHLY",
"replace_variables": true
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$rel_scheduled_msg = $project->createRelativeScheduledMessage([
'content' => "Hi [[contact.name]], just following up!",
'group_id' => "GC123123123123123123",
'time_of_day' => "15:07",
'date_variable' => "date",
'offset_scale' => "D",
'offset_count' => 3,
'rrule' => "FREQ=MONTHLY",
'replace_variables' => true
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
rel_scheduled_msg = project.createRelativeScheduledMessage(
content = "Hi [[contact.name]], just following up!",
group_id = "GC123123123123123123",
time_of_day = "15:07",
date_variable = "date",
offset_scale = "D",
offset_count = 3,
rrule = "FREQ=MONTHLY",
replace_variables = True
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
rel_scheduled_msg = project.create_relative_scheduled_message({
'content' => "Hi [[contact.name]], just following up!",
'group_id' => "GC123123123123123123",
'time_of_day' => "15:07",
'date_variable' => "date",
'offset_scale' => "D",
'offset_count' => 3,
'rrule' => "FREQ=MONTHLY",
'replace_variables' => true
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.createRelativeScheduledMessage({
content: "Hi [[contact.name]], just following up!",
group_id: "GC123123123123123123",
time_of_day: "15:07",
date_variable: "date",
offset_scale: "D",
offset_count: 3,
rrule: "FREQ=MONTHLY",
replace_variables: true
}, function(err, rel_scheduled_msg) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.RelativeScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = project.createRelativeScheduledMessage(Util.options(
"content", "Hi [[contact.name]], just following up!",
"group_id", "GC123123123123123123",
"time_of_day", "15:07",
"date_variable", "date",
"offset_scale", "D",
"offset_count", 3,
"rrule", "FREQ=MONTHLY",
"replace_variables", true
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = await project.CreateRelativeScheduledMessageAsync(Util.Options(
"content", "Hi [[contact.name]], just following up!",
"group_id", "GC123123123123123123",
"time_of_day", "15:07",
"date_variable", "date",
"offset_scale", "D",
"offset_count", 3,
"rrule", "FREQ=MONTHLY",
"replace_variables", true
));
|
Query relative scheduled messages
GET /v1/projects/<project_id>/relative_scheduled Queries relative scheduled messages within the given project.
Argumentsmessage_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 | 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 TypeRaw API: Query result of RelativeScheduledMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/relative_scheduled?message_type=sms"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryRelativeScheduledMessages([
'message_type' => "sms"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$rel_scheduled_msg = $cursor->next();
// do something with $rel_scheduled_msg
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryRelativeScheduledMessages(
message_type = "sms"
)
for rel_scheduled_msg in cursor.limit(50):
# do something with rel_scheduled_msg
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_relative_scheduled_messages({
'message_type' => "sms"
})
cursor.limit(50).each { |rel_scheduled_msg|
# do something with rel_scheduled_msg
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryRelativeScheduledMessages({
message_type: "sms"
});
cursor.limit(50).each(function(err, rel_scheduled_msg) {
if (err) {
// do something with err
}
if (rel_scheduled_msg) {
// do something with rel_scheduled_msg
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<RelativeScheduledMessage> cursor = project.queryRelativeScheduledMessages(Util.options(
"message_type", "sms"
));
cursor.limit(50);
while (cursor.hasNext()) {
RelativeScheduledMessage rel_scheduled_msg = cursor.next();
// do something with rel_scheduled_msg
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<RelativeScheduledMessage> cursor = project.QueryRelativeScheduledMessages(Util.Options(
"message_type", "sms"
));
List<RelativeScheduledMessage> list = await query.Limit(50).AllAsync();
foreach (RelativeScheduledMessage rel_scheduled_msg in list) {
// do something with rel_scheduled_msg
}
|
Update relative scheduled message
POST /v1/projects/<project_id>/relative_scheduled/<rel_scheduled_msg_id> Updates writable fields on the given relative scheduled message.
Argumentscontent | 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 | 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 | 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 | 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 TypeClient libraries: undefined Raw API: RelativeScheduledMessage Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/relative_scheduled/REL_SCHEDULED_MSG_ID" \
-H "Content-Type: application/json" \
-d '{
"content": "hello world!",
"time_of_day": "15:07",
"date_variable": "date",
"offset_scale": "D",
"offset_count": 3,
"rrule": "COUNT=1",
"timezone_id": "America/Los_Angeles",
"route_id": "PN4d246818d0ecd1fa",
"service_id": "SV3d246818d0e3d1fb",
"replace_variables": false,
"vars": {
"foo": "bar",
"baz": 42
},
"label_ids": [
"LB4f3dac27154653e0"
]
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$rel_scheduled_msg = $project->initRelativeScheduledMessageById($rel_scheduled_msg_id);
$rel_scheduled_msg->content = "hello world!";
$rel_scheduled_msg->time_of_day = "15:07";
$rel_scheduled_msg->date_variable = "date";
$rel_scheduled_msg->offset_scale = "D";
$rel_scheduled_msg->offset_count = 3;
$rel_scheduled_msg->rrule = "COUNT=1";
$rel_scheduled_msg->timezone_id = "America/Los_Angeles";
$rel_scheduled_msg->route_id = "PN4d246818d0ecd1fa";
$rel_scheduled_msg->service_id = "SV3d246818d0e3d1fb";
$rel_scheduled_msg->replace_variables = false;
$rel_scheduled_msg->vars->foo = "bar";
$rel_scheduled_msg->vars->baz = 42;
$rel_scheduled_msg->label_ids = ["LB4f3dac27154653e0"];
$rel_scheduled_msg->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
rel_scheduled_msg = project.initRelativeScheduledMessageById(rel_scheduled_msg_id)
rel_scheduled_msg.content = "hello world!"
rel_scheduled_msg.time_of_day = "15:07"
rel_scheduled_msg.date_variable = "date"
rel_scheduled_msg.offset_scale = "D"
rel_scheduled_msg.offset_count = 3
rel_scheduled_msg.rrule = "COUNT=1"
rel_scheduled_msg.timezone_id = "America/Los_Angeles"
rel_scheduled_msg.route_id = "PN4d246818d0ecd1fa"
rel_scheduled_msg.service_id = "SV3d246818d0e3d1fb"
rel_scheduled_msg.replace_variables = False
rel_scheduled_msg.vars.foo = "bar"
rel_scheduled_msg.vars.baz = 42
rel_scheduled_msg.label_ids = ["LB4f3dac27154653e0"]
rel_scheduled_msg.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
rel_scheduled_msg = project.init_relative_scheduled_message_by_id(rel_scheduled_msg_id)
rel_scheduled_msg.content = "hello world!"
rel_scheduled_msg.time_of_day = "15:07"
rel_scheduled_msg.date_variable = "date"
rel_scheduled_msg.offset_scale = "D"
rel_scheduled_msg.offset_count = 3
rel_scheduled_msg.rrule = "COUNT=1"
rel_scheduled_msg.timezone_id = "America/Los_Angeles"
rel_scheduled_msg.route_id = "PN4d246818d0ecd1fa"
rel_scheduled_msg.service_id = "SV3d246818d0e3d1fb"
rel_scheduled_msg.replace_variables = false
rel_scheduled_msg.vars.foo = "bar"
rel_scheduled_msg.vars.baz = 42
rel_scheduled_msg.label_ids = ["LB4f3dac27154653e0"]
rel_scheduled_msg.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var rel_scheduled_msg = project.initRelativeScheduledMessageById(rel_scheduled_msg_id);
rel_scheduled_msg.content = "hello world!";
rel_scheduled_msg.time_of_day = "15:07";
rel_scheduled_msg.date_variable = "date";
rel_scheduled_msg.offset_scale = "D";
rel_scheduled_msg.offset_count = 3;
rel_scheduled_msg.rrule = "COUNT=1";
rel_scheduled_msg.timezone_id = "America/Los_Angeles";
rel_scheduled_msg.route_id = "PN4d246818d0ecd1fa";
rel_scheduled_msg.service_id = "SV3d246818d0e3d1fb";
rel_scheduled_msg.replace_variables = false;
rel_scheduled_msg.vars.foo = "bar";
rel_scheduled_msg.vars.baz = 42;
rel_scheduled_msg.label_ids = ["LB4f3dac27154653e0"];
rel_scheduled_msg.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.RelativeScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = project.initRelativeScheduledMessageById(rel_scheduled_msg_id);
rel_scheduled_msg.setContent("hello world!");
rel_scheduled_msg.setTimeOfDay("15:07");
rel_scheduled_msg.setDateVariable("date");
rel_scheduled_msg.setOffsetScale("D");
rel_scheduled_msg.setOffsetCount(3);
rel_scheduled_msg.setRrule("COUNT=1");
rel_scheduled_msg.setTimezoneId("America/Los_Angeles");
rel_scheduled_msg.setRouteId("PN4d246818d0ecd1fa");
rel_scheduled_msg.setServiceId("SV3d246818d0e3d1fb");
rel_scheduled_msg.setReplaceVariables(false);
rel_scheduled_msg.vars().set("foo", "bar");
rel_scheduled_msg.vars().set("baz", 42);
rel_scheduled_msg.setLabelIds(new Object[] {"LB4f3dac27154653e0"});
rel_scheduled_msg.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = project.InitRelativeScheduledMessageById(rel_scheduled_msg_id);
rel_scheduled_msg.Content = "hello world!";
rel_scheduled_msg.TimeOfDay = "15:07";
rel_scheduled_msg.DateVariable = "date";
rel_scheduled_msg.OffsetScale = "D";
rel_scheduled_msg.OffsetCount = 3;
rel_scheduled_msg.Rrule = "COUNT=1";
rel_scheduled_msg.TimezoneId = "America/Los_Angeles";
rel_scheduled_msg.RouteId = "PN4d246818d0ecd1fa";
rel_scheduled_msg.ServiceId = "SV3d246818d0e3d1fb";
rel_scheduled_msg.ReplaceVariables = false;
rel_scheduled_msg.Vars.Set("foo", "bar");
rel_scheduled_msg.Vars.Set("baz", 42);
rel_scheduled_msg.LabelIds = new Object[] {"LB4f3dac27154653e0"};
await rel_scheduled_msg.SaveAsync();
|
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.
ArgumentsNone Return Typeundefined Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/relative_scheduled/REL_SCHEDULED_MSG_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$rel_scheduled_msg = $project->initRelativeScheduledMessageById($rel_scheduled_msg_id);
$rel_scheduled_msg->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
rel_scheduled_msg = project.initRelativeScheduledMessageById(rel_scheduled_msg_id)
rel_scheduled_msg.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
rel_scheduled_msg = project.init_relative_scheduled_message_by_id(rel_scheduled_msg_id)
rel_scheduled_msg.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var rel_scheduled_msg = project.initRelativeScheduledMessageById(rel_scheduled_msg_id);
rel_scheduled_msg.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.RelativeScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = project.initRelativeScheduledMessageById(rel_scheduled_msg_id);
rel_scheduled_msg.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = project.InitRelativeScheduledMessageById(rel_scheduled_msg_id);
await rel_scheduled_msg.DeleteAsync();
|
Get scheduled message by ID
GET /v1/projects/<project_id>/scheduled/<scheduled_msg_id> Retrieves the scheduled message with the given ID.
ArgumentsNone Return TypeScheduledMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/scheduled/SCHEDULED_MSG_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$scheduled_msg = $project->getScheduledMessageById($scheduled_msg_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
scheduled_msg = project.getScheduledMessageById(scheduled_msg_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
scheduled_msg = project.get_scheduled_message_by_id(scheduled_msg_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getScheduledMessageById(scheduled_msg_id, function(err, scheduled_msg) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.ScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
ScheduledMessage scheduled_msg = project.getScheduledMessageById(scheduled_msg_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
ScheduledMessage scheduled_msg = await project.GetScheduledMessageByIdAsync(scheduled_msg_id);
|
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.
ArgumentsNone Return TypeRelativeScheduledMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/relative_scheduled/REL_SCHEDULED_MSG_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$rel_scheduled_msg = $project->getRelativeScheduledMessageById($rel_scheduled_msg_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
rel_scheduled_msg = project.getRelativeScheduledMessageById(rel_scheduled_msg_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
rel_scheduled_msg = project.get_relative_scheduled_message_by_id(rel_scheduled_msg_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getRelativeScheduledMessageById(rel_scheduled_msg_id, function(err, rel_scheduled_msg) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.RelativeScheduledMessage;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = project.getRelativeScheduledMessageById(rel_scheduled_msg_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
RelativeScheduledMessage rel_scheduled_msg = await project.GetRelativeScheduledMessageByIdAsync(rel_scheduled_msg_id);
|
Contacts | |
Object Type: Contact
Attributesid |
string, max 34 characters | read-only |
name |
string | 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 |
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 |
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 |
ID of the project this contact belongs to
| read-only |
|
ExampleTelerivet_Contact JSON: Contact JSON: Telerivet::Contact JSON: Contact JSON: Contact JSON: Contact JSON: {
"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 ).
Argumentsname | string, optional | 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 | 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 TypeContact Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts" \
-H "Content-Type: application/json" \
-d '{
"name": "John Smith",
"phone_number": "5550123",
"add_group_ids": [
"CG37f46ac132ef1542",
"CG47f46ac232ee0123"
],
"vars": {
"email": "jsmith@example.com",
"birthdate": "1953-01-04",
"your_id": "12942938"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->getOrCreateContact([
'name' => "John Smith",
'phone_number' => "5550123",
'add_group_ids' => ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
'vars' => ['email' => "jsmith@example.com", 'birthdate' => "1953-01-04", 'your_id' => "12942938"]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.getOrCreateContact(
name = "John Smith",
phone_number = "5550123",
add_group_ids = ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
vars = {'email': "jsmith@example.com", 'birthdate': "1953-01-04", 'your_id': "12942938"}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.get_or_create_contact({
'name' => "John Smith",
'phone_number' => "5550123",
'add_group_ids' => ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
'vars' => {'email' => "jsmith@example.com", 'birthdate' => "1953-01-04", 'your_id' => "12942938"}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getOrCreateContact({
name: "John Smith",
phone_number: "5550123",
add_group_ids: ["CG37f46ac132ef1542", "CG47f46ac232ee0123"],
vars: {'email': "jsmith@example.com", 'birthdate': "1953-01-04", 'your_id': "12942938"}
}, function(err, contact) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.getOrCreateContact(Util.options(
"name", "John Smith",
"phone_number", "5550123",
"add_group_ids", new Object[] {"CG37f46ac132ef1542", "CG47f46ac232ee0123"},
"vars", Util.options("email", "jsmith@example.com", "birthdate", "1953-01-04", "your_id", "12942938")
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = await project.GetOrCreateContactAsync(Util.Options(
"name", "John Smith",
"phone_number", "5550123",
"add_group_ids", new Object[] {"CG37f46ac132ef1542", "CG47f46ac232ee0123"},
"vars", Util.Options("email", "jsmith@example.com", "birthdate", "1953-01-04", "your_id", "12942938")
));
|
Query contacts
GET /v1/projects/<project_id>/contacts Queries contacts within the given project.
Argumentsgroup_id | string ID of Group, optional Filter contacts within a group
| name | string, optional 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 TypeRaw API: Query result of Contact Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts?name[prefix]=John&last_message_time[min]=1733350916"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryContacts([
'sort' => "name",
'sort_dir' => "desc",
'offset' => 50
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$contact = $cursor->next();
// do something with $contact
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryContacts(
sort = "name",
sort_dir = "desc",
offset = 50
)
for contact in cursor.limit(50):
# do something with contact
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_contacts({
'sort' => "name",
'sort_dir' => "desc",
'offset' => 50
})
cursor.limit(50).each { |contact|
# do something with contact
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryContacts({
sort: "name",
sort_dir: "desc",
offset: 50
});
cursor.limit(50).each(function(err, contact) {
if (err) {
// do something with err
}
if (contact) {
// do something with contact
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Contact> cursor = project.queryContacts(Util.options(
"sort", "name",
"sort_dir", "desc",
"offset", 50
));
cursor.limit(50);
while (cursor.hasNext()) {
Contact contact = cursor.next();
// do something with contact
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Contact> cursor = project.QueryContacts(Util.Options(
"sort", "name",
"sort_dir", "desc",
"offset", 50
));
List<Contact> list = await query.Limit(50).AllAsync();
foreach (Contact contact in list) {
// do something with contact
}
|
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.
Argumentscontacts | 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 Typeobject Return Value Propertiescontacts |
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 RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/import_contacts" \
-H "Content-Type: application/json" \
-d '{
"contacts": [
{
"name": "John Smith",
"phone_number": "5550123"
},
{
"name": "Jane Doe",
"phone_number": "5550124",
"vars": {
"foo": "bar",
"baz": 12
}
}
],
"add_group_ids": [
"CG37f46ac132ef1542",
"CG47f46ac232ee0123"
]
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$res = $project->importContacts([
'contacts' => [['name' => "John Smith", 'phone_number' => "5550123"], ['name' => "Jane Doe", 'phone_number' => "5550124", 'vars' => ['foo' => "bar", 'baz' => 12]]],
'add_group_ids' => ["CG37f46ac132ef1542", "CG47f46ac232ee0123"]
]);
foreach ($res['contacts'] as $contact_info) {
$contact_id = $contact_info['id'];
// optional: save contact id in your database so you can easily update the contact later
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
res = project.importContacts(
contacts = [{'name': "John Smith", 'phone_number': "5550123"}, {'name': "Jane Doe", 'phone_number': "5550124", 'vars': {'foo': "bar", 'baz': 12}}],
add_group_ids = ["CG37f46ac132ef1542", "CG47f46ac232ee0123"]
)
for contact_info in res['contacts']:
contact_id = contact_info['id']
# optional: save contact id in your database so you can easily update the contact later
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
res = project.import_contacts({
'contacts' => [{'name' => "John Smith", 'phone_number' => "5550123"}, {'name' => "Jane Doe", 'phone_number' => "5550124", 'vars' => {'foo' => "bar", 'baz' => 12}}],
'add_group_ids' => ["CG37f46ac132ef1542", "CG47f46ac232ee0123"]
})
res['contacts'].each { |contact_info|
contact_id = contact_info['id']
# optional: save contact id in your database so you can easily update the contact later
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.importContacts({
contacts: [{'name': "John Smith", 'phone_number': "5550123"}, {'name': "Jane Doe", 'phone_number': "5550124", 'vars': {'foo': "bar", 'baz': 12}}],
add_group_ids: ["CG37f46ac132ef1542", "CG47f46ac232ee0123"]
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
JSONObject res = project.importContacts(Util.options(
"contacts", new Object[] {Util.options("name", "John Smith", "phone_number", "5550123"), Util.options("name", "Jane Doe", "phone_number", "5550124", "vars", Util.options("foo", "bar", "baz", 12))},
"add_group_ids", new Object[] {"CG37f46ac132ef1542", "CG47f46ac232ee0123"}
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
JObject res = await project.ImportContactsAsync(Util.Options(
"contacts", new Object[] {Util.Options("name", "John Smith", "phone_number", "5550123"), Util.Options("name", "Jane Doe", "phone_number", "5550124", "vars", Util.Options("foo", "bar", "baz", 12))},
"add_group_ids", new Object[] {"CG37f46ac132ef1542", "CG47f46ac232ee0123"}
));
|
Delete a contact
DELETE /v1/projects/<project_id>/contacts/<contact_id> ArgumentsNone Return Typeundefined Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$contact->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
contact.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
contact.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
contact.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
contact.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
await contact.DeleteAsync();
|
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.)
ArgumentsNone Return Typearray Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contact_fields"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->getContactFields();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.getContactFields()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.get_contact_fields()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getContactFields(function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.getContactFields();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.GetContactFieldsAsync();
|
Get contact by ID
GET /v1/projects/<project_id>/contacts/<contact_id> Retrieves the contact with the given ID.
ArgumentsNone Return TypeContact Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->getContactById($contact_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.getContactById(contact_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.get_contact_by_id(contact_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getContactById(contact_id, function(err, contact) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.getContactById(contact_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = await project.GetContactByIdAsync(contact_id);
|
Update contact details
POST /v1/projects/<project_id>/contacts/<contact_id> Updates writable fields on the given contact
Argumentsname | string, optional | 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 TypeClient libraries: undefined Raw API: Contact Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "John Smith",
"phone_number": "+16505550123",
"send_blocked": false,
"conversation_status": "active",
"vars": {
"email": "jsmith@example.com",
"birthdate": "1953-01-05"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$contact->name = "John Smith";
$contact->phone_number = "+16505550123";
$contact->send_blocked = false;
$contact->conversation_status = "active";
$contact->vars->email = "jsmith@example.com";
$contact->vars->birthdate = "1953-01-05";
$contact->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
contact.name = "John Smith"
contact.phone_number = "+16505550123"
contact.send_blocked = False
contact.conversation_status = "active"
contact.vars.email = "jsmith@example.com"
contact.vars.birthdate = "1953-01-05"
contact.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
contact.name = "John Smith"
contact.phone_number = "+16505550123"
contact.send_blocked = false
contact.conversation_status = "active"
contact.vars.email = "jsmith@example.com"
contact.vars.birthdate = "1953-01-05"
contact.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
contact.name = "John Smith";
contact.phone_number = "+16505550123";
contact.send_blocked = false;
contact.conversation_status = "active";
contact.vars.email = "jsmith@example.com";
contact.vars.birthdate = "1953-01-05";
contact.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
contact.setName("John Smith");
contact.setPhoneNumber("+16505550123");
contact.setSendBlocked(false);
contact.setConversationStatus("active");
contact.vars().set("email", "jsmith@example.com");
contact.vars().set("birthdate", "1953-01-05");
contact.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
contact.Name = "John Smith";
contact.PhoneNumber = "+16505550123";
contact.SendBlocked = false;
contact.ConversationStatus = "active";
contact.Vars.Set("email", "jsmith@example.com");
contact.Vars.Set("birthdate", "1953-01-05");
await contact.SaveAsync();
|
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.
Argumentsdirection | 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 | 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 | ID of the broadcast containing the message
Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?) | scheduled_id | 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 TypeRaw API: Query result of Message Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID/messages?direction=incoming&message_type=sms"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$cursor = $contact->queryMessages([
'direction' => "incoming",
'message_type' => "sms"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$message = $cursor->next();
// do something with $message
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
cursor = contact.queryMessages(
direction = "incoming",
message_type = "sms"
)
for message in cursor.limit(50):
# do something with message
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
cursor = contact.query_messages({
'direction' => "incoming",
'message_type' => "sms"
})
cursor.limit(50).each { |message|
# do something with message
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
cursor = contact.queryMessages({
direction: "incoming",
message_type: "sms"
});
cursor.limit(50).each(function(err, message) {
if (err) {
// do something with err
}
if (message) {
// do something with message
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
APICursor<Message> cursor = contact.queryMessages(Util.options(
"direction", "incoming",
"message_type", "sms"
));
cursor.limit(50);
while (cursor.hasNext()) {
Message message = cursor.next();
// do something with message
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
APICursor<Message> cursor = contact.QueryMessages(Util.Options(
"direction", "incoming",
"message_type", "sms"
));
List<Message> list = await query.Limit(50).AllAsync();
foreach (Message message in list) {
// do something with message
}
|
Remove contact from a group
DELETE /v1/projects/<project_id>/groups/<group_id>/contacts/<contact_id> Removes this contact from a group.
ArgumentsNone Return Typeundefined Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID/contacts/CONTACT_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$group = $project->initGroupById($group_id);
$contact->removeFromGroup($group);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
group = project.initGroupById(group_id)
contact.removeFromGroup(group)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
group = project.init_group_by_id(group_id)
contact.remove_from_group(group)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
var group = project.initGroupById(group_id);
contact.removeFromGroup(group, function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
Group group = project.initGroupById(group_id);
contact.removeFromGroup(group);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
Group group = project.InitGroupById(group_id);
await contact.RemoveFromGroupAsync(group);
|
Add contact to a group
PUT /v1/projects/<project_id>/groups/<group_id>/contacts/<contact_id> Adds this contact to a group.
ArgumentsNone Return Typeundefined Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID/contacts/CONTACT_ID" \
-X PUT
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$group = $project->initGroupById($group_id);
$contact->addToGroup($group);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
group = project.initGroupById(group_id)
contact.addToGroup(group)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
group = project.init_group_by_id(group_id)
contact.add_to_group(group)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
var group = project.initGroupById(group_id);
contact.addToGroup(group, function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
Group group = project.initGroupById(group_id);
contact.addToGroup(group);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
Group group = project.InitGroupById(group_id);
await contact.AddToGroupAsync(group);
|
Query service states for a contact
GET /v1/projects/<project_id>/contacts/<contact_id>/states Queries this contact's current states for any service
Argumentsid | string, optional 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 TypeRaw API: Query result of ContactServiceState Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID/states?id=q1"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$cursor = $contact->queryServiceStates([
'id' => "q1"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$state = $cursor->next();
// do something with $state
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
cursor = contact.queryServiceStates(
id = "q1"
)
for state in cursor.limit(50):
# do something with state
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
cursor = contact.query_service_states({
'id' => "q1"
})
cursor.limit(50).each { |state|
# do something with state
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
cursor = contact.queryServiceStates({
id: "q1"
});
cursor.limit(50).each(function(err, state) {
if (err) {
// do something with err
}
if (state) {
// do something with state
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
APICursor<ContactServiceState> cursor = contact.queryServiceStates(Util.options(
"id", "q1"
));
cursor.limit(50);
while (cursor.hasNext()) {
ContactServiceState state = cursor.next();
// do something with state
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
APICursor<ContactServiceState> cursor = contact.QueryServiceStates(Util.Options(
"id", "q1"
));
List<ContactServiceState> list = await query.Limit(50).AllAsync();
foreach (ContactServiceState state in list) {
// do something with state
}
|
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).
Argumentstime_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 TypeRaw API: Query result of DataRow Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID/rows"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$cursor = $contact->queryDataRows();
$cursor->limit(50);
while ($cursor->hasNext()) {
$row = $cursor->next();
// do something with $row
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
cursor = contact.queryDataRows()
for row in cursor.limit(50):
# do something with row
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
cursor = contact.query_data_rows()
cursor.limit(50).each { |row|
# do something with row
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
cursor = contact.queryDataRows();
cursor.limit(50).each(function(err, row) {
if (err) {
// do something with err
}
if (row) {
// do something with row
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
APICursor<DataRow> cursor = contact.queryDataRows();
cursor.limit(50);
while (cursor.hasNext()) {
DataRow row = cursor.next();
// do something with row
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
APICursor<DataRow> cursor = contact.QueryDataRows();
List<DataRow> list = await query.Limit(50).AllAsync();
foreach (DataRow row in list) {
// do something with row
}
|
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)
Argumentsmessage_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 | 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 TypeRaw API: Query result of ScheduledMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID/scheduled?message_type=sms&next_time[min]=1741126916"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$cursor = $contact->queryScheduledMessages([
'message_type' => "sms",
'next_time' => ['min' => 1741126916]
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$scheduled_msg = $cursor->next();
// do something with $scheduled_msg
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
cursor = contact.queryScheduledMessages(
message_type = "sms",
next_time = {'min': 1741126916}
)
for scheduled_msg in cursor.limit(50):
# do something with scheduled_msg
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
cursor = contact.query_scheduled_messages({
'message_type' => "sms",
'next_time' => {'min' => 1741126916}
})
cursor.limit(50).each { |scheduled_msg|
# do something with scheduled_msg
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
cursor = contact.queryScheduledMessages({
message_type: "sms",
next_time: {'min': 1741126916}
});
cursor.limit(50).each(function(err, scheduled_msg) {
if (err) {
// do something with err
}
if (scheduled_msg) {
// do something with scheduled_msg
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
APICursor<ScheduledMessage> cursor = contact.queryScheduledMessages(Util.options(
"message_type", "sms",
"next_time", Util.options("min", 1741126916)
));
cursor.limit(50);
while (cursor.hasNext()) {
ScheduledMessage scheduled_msg = cursor.next();
// do something with scheduled_msg
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
APICursor<ScheduledMessage> cursor = contact.QueryScheduledMessages(Util.Options(
"message_type", "sms",
"next_time", Util.Options("min", 1741126916)
));
List<ScheduledMessage> list = await query.Limit(50).AllAsync();
foreach (ScheduledMessage scheduled_msg in list) {
// do something with scheduled_msg
}
|
Query groups for a contact
GET /v1/projects/<project_id>/contacts/<contact_id>/groups Queries groups for which this contact is a member.
Argumentsname | string, optional 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 TypeRaw API: Query result of Group Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contacts/CONTACT_ID/groups"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$contact = $project->initContactById($contact_id);
$cursor = $contact->queryGroups();
$cursor->limit(50);
while ($cursor->hasNext()) {
$group = $cursor->next();
// do something with $group
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
contact = project.initContactById(contact_id)
cursor = contact.queryGroups()
for group in cursor.limit(50):
# do something with group
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
contact = project.init_contact_by_id(contact_id)
cursor = contact.query_groups()
cursor.limit(50).each { |group|
# do something with group
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var contact = project.initContactById(contact_id);
cursor = contact.queryGroups();
cursor.limit(50).each(function(err, group) {
if (err) {
// do something with err
}
if (group) {
// do something with group
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Contact;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Contact contact = project.initContactById(contact_id);
APICursor<Group> cursor = contact.queryGroups();
cursor.limit(50);
while (cursor.hasNext()) {
Group group = cursor.next();
// do something with group
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Contact contact = project.InitContactById(contact_id);
APICursor<Group> cursor = contact.QueryGroups();
List<Group> list = await query.Limit(50).AllAsync();
foreach (Group group in list) {
// do something with group
}
|
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.
Argumentsname | string, max 64 characters, optional Display name for the field
| type | int, optional 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 Typeobject Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/contact_fields/VARIABLE" \
-H "Content-Type: application/json" \
-d '{
"name": "Age",
"type": "number",
"order": 2
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->setContactFieldMetadata("age", [
'name' => "Age",
'type' => "number",
'order' => 2
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.setContactFieldMetadata("age",
name = "Age",
type = "number",
order = 2
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.set_contact_field_metadata("age", {
'name' => "Age",
'type' => "number",
'order' => 2
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.setContactFieldMetadata("age", {
name: "Age",
type: "number",
order: 2
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.setContactFieldMetadata("age", Util.options(
"name", "Age",
"type", "number",
"order", 2
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.SetContactFieldMetadataAsync("age", Util.Options(
"name", "Age",
"type", "number",
"order", 2
));
|
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.
Attributesid |
string, max 34 characters | read-only |
name |
string | 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 |
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 |
|
ExampleTelerivet_Phone JSON: Phone JSON: Telerivet::Phone JSON: Phone JSON: Phone JSON: Phone JSON: {
"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.
Attributesid |
string, max 34 characters Telerivet's internal ID for the route
| read-only |
name |
string | 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 |
ID of the project this route belongs to
| read-only |
|
ExampleTelerivet_Route JSON: Route JSON: Telerivet::Route JSON: Route JSON: Route JSON: Route JSON: {
"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.
Argumentsname | string, optional 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 TypeRaw API: Query result of Phone Permission RequiredView routes | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/phones"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryPhones();
$cursor->limit(50);
while ($cursor->hasNext()) {
$phone = $cursor->next();
// do something with $phone
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryPhones()
for phone in cursor.limit(50):
# do something with phone
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_phones()
cursor.limit(50).each { |phone|
# do something with phone
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryPhones();
cursor.limit(50).each(function(err, phone) {
if (err) {
// do something with err
}
if (phone) {
// do something with phone
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Phone> cursor = project.queryPhones();
cursor.limit(50);
while (cursor.hasNext()) {
Phone phone = cursor.next();
// do something with phone
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Phone> cursor = project.QueryPhones();
List<Phone> list = await query.Limit(50).AllAsync();
foreach (Phone phone in list) {
// do something with phone
}
|
Get basic route by ID
GET /v1/projects/<project_id>/phones/<phone_id> Retrieves the basic route with the given ID.
ArgumentsNone Return TypePhone Permission RequiredView routes | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/phones/PHONE_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$phone = $project->getPhoneById($phone_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
phone = project.getPhoneById(phone_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
phone = project.get_phone_by_id(phone_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getPhoneById(phone_id, function(err, phone) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Phone;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Phone phone = project.getPhoneById(phone_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Phone phone = await project.GetPhoneByIdAsync(phone_id);
|
Query custom routes
GET /v1/projects/<project_id>/routes Queries custom routes that can be used to send messages (not including Phones).
Argumentsname | string, optional 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 TypeRaw API: Query result of Route Permission RequiredView routes | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/routes"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryRoutes();
$cursor->limit(50);
while ($cursor->hasNext()) {
$route = $cursor->next();
// do something with $route
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryRoutes()
for route in cursor.limit(50):
# do something with route
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_routes()
cursor.limit(50).each { |route|
# do something with route
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryRoutes();
cursor.limit(50).each(function(err, route) {
if (err) {
// do something with err
}
if (route) {
// do something with route
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Route> cursor = project.queryRoutes();
cursor.limit(50);
while (cursor.hasNext()) {
Route route = cursor.next();
// do something with route
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Route> cursor = project.QueryRoutes();
List<Route> list = await query.Limit(50).AllAsync();
foreach (Route route in list) {
// do something with route
}
|
Get custom route by ID
GET /v1/projects/<project_id>/routes/<route_id> Gets a custom route by ID
ArgumentsNone Return TypeRoute Permission RequiredView routes | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/routes/ROUTE_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$route = $project->getRouteById($route_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
route = project.getRouteById(route_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
route = project.get_route_by_id(route_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getRouteById(route_id, function(err, route) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Route;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Route route = project.getRouteById(route_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Route route = await project.GetRouteByIdAsync(route_id);
|
Query messages for a basic route
GET /v1/projects/<project_id>/phones/<phone_id>/messages Queries messages sent or received by this basic route.
Argumentsdirection | 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 | 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 | ID of the broadcast containing the message
Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?) | scheduled_id | 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 TypeRaw API: Query result of Message Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/phones/PHONE_ID/messages?direction=incoming&message_type=sms"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$phone = $project->initPhoneById($phone_id);
$cursor = $phone->queryMessages([
'direction' => "incoming",
'message_type' => "sms"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$message = $cursor->next();
// do something with $message
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
phone = project.initPhoneById(phone_id)
cursor = phone.queryMessages(
direction = "incoming",
message_type = "sms"
)
for message in cursor.limit(50):
# do something with message
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
phone = project.init_phone_by_id(phone_id)
cursor = phone.query_messages({
'direction' => "incoming",
'message_type' => "sms"
})
cursor.limit(50).each { |message|
# do something with message
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var phone = project.initPhoneById(phone_id);
cursor = phone.queryMessages({
direction: "incoming",
message_type: "sms"
});
cursor.limit(50).each(function(err, message) {
if (err) {
// do something with err
}
if (message) {
// do something with message
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Phone;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Phone phone = project.initPhoneById(phone_id);
APICursor<Message> cursor = phone.queryMessages(Util.options(
"direction", "incoming",
"message_type", "sms"
));
cursor.limit(50);
while (cursor.hasNext()) {
Message message = cursor.next();
// do something with message
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Phone phone = project.InitPhoneById(phone_id);
APICursor<Message> cursor = phone.QueryMessages(Util.Options(
"direction", "incoming",
"message_type", "sms"
));
List<Message> list = await query.Limit(50).AllAsync();
foreach (Message message in list) {
// do something with message
}
|
Update basic route
POST /v1/projects/<project_id>/phones/<phone_id> Updates writable fields on the given basic route.
Argumentsname | string, optional | 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 TypeClient libraries: undefined Raw API: Phone Permission RequiredEdit routes | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/phones/PHONE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Android Phone 1",
"phone_number": "+16505550001",
"send_paused": false,
"vars": {
"foo": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$phone = $project->initPhoneById($phone_id);
$phone->name = "Android Phone 1";
$phone->phone_number = "+16505550001";
$phone->send_paused = false;
$phone->vars->foo = 42;
$phone->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
phone = project.initPhoneById(phone_id)
phone.name = "Android Phone 1"
phone.phone_number = "+16505550001"
phone.send_paused = False
phone.vars.foo = 42
phone.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
phone = project.init_phone_by_id(phone_id)
phone.name = "Android Phone 1"
phone.phone_number = "+16505550001"
phone.send_paused = false
phone.vars.foo = 42
phone.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var phone = project.initPhoneById(phone_id);
phone.name = "Android Phone 1";
phone.phone_number = "+16505550001";
phone.send_paused = false;
phone.vars.foo = 42;
phone.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Phone;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Phone phone = project.initPhoneById(phone_id);
phone.setName("Android Phone 1");
phone.setPhoneNumber("+16505550001");
phone.setSendPaused(false);
phone.vars().set("foo", 42);
phone.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Phone phone = project.InitPhoneById(phone_id);
phone.Name = "Android Phone 1";
phone.PhoneNumber = "+16505550001";
phone.SendPaused = false;
phone.Vars.Set("foo", 42);
await phone.SaveAsync();
|
Update custom route
POST /v1/projects/<project_id>/routes/<route_id> Saves any fields or custom variables that have changed for this custom route.
Argumentsname | string, optional | 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 TypeClient libraries: undefined Raw API: Route Permission RequiredEdit routes | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/routes/ROUTE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Custom Route",
"vars": {
"foo": "bar",
"baz": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$route = $project->initRouteById($route_id);
$route->name = "Custom Route";
$route->vars->foo = "bar";
$route->vars->baz = 42;
$route->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
route = project.initRouteById(route_id)
route.name = "Custom Route"
route.vars.foo = "bar"
route.vars.baz = 42
route.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
route = project.init_route_by_id(route_id)
route.name = "Custom Route"
route.vars.foo = "bar"
route.vars.baz = 42
route.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var route = project.initRouteById(route_id);
route.name = "Custom Route";
route.vars.foo = "bar";
route.vars.baz = 42;
route.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Route;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Route route = project.initRouteById(route_id);
route.setName("Custom Route");
route.vars().set("foo", "bar");
route.vars().set("baz", 42);
route.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Route route = project.InitRouteById(route_id);
route.Name = "Custom Route";
route.Vars.Set("foo", "bar");
route.Vars.Set("baz", 42);
await route.SaveAsync();
|
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.
Attributesid |
string, max 34 characters | read-only |
name |
string | updatable |
service_type |
string | 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 |
ID of the project this service belongs to
| read-only |
response_table_id |
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 |
|
ExampleTelerivet_Service JSON: Service JSON: Telerivet::Service JSON: Service JSON: Service JSON: Service JSON: {
"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.
Attributesid |
string, max 63 characters Arbitrary string representing the contact's current state for this service, e.g. 'q1', 'q2', etc.
| updatable |
contact_id |
| read-only |
service_id |
| 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 |
ID of the project this contact/service state belongs to
| read-only |
|
ExampleTelerivet_ContactServiceState JSON: ContactServiceState JSON: Telerivet::ContactServiceState JSON: ContactServiceState JSON: ContactServiceState JSON: ContactServiceState JSON: {
"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.)
Argumentscontext | 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 | 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 Typeobject Return Value Propertiesreturn_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 RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/invoke" \
-H "Content-Type: application/json" \
-d '{
"context": "contact",
"contact_id": "contact.id",
"variables": {
"first_name": "John",
"age": 30
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$service->invoke([
'context' => "contact",
'contact_id' => $contact->id,
'variables' => ['first_name' => "John", 'age' => 30]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
service.invoke(
context = "contact",
contact_id = contact.id,
variables = {'first_name': "John", 'age': 30}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
service.invoke({
'context' => "contact",
'contact_id' => contact.id,
'variables' => {'first_name' => "John", 'age' => 30}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
service.invoke({
context: "contact",
contact_id: contact.id,
variables: {'first_name': "John", 'age': 30}
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
service.invoke(Util.options(
"context", "contact",
"contact_id", contact.id,
"variables", Util.options("first_name", "John", "age", 30)
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
await service.InvokeAsync(Util.Options(
"context", "contact",
"contact_id", contact.id,
"variables", Util.Options("first_name", "John", "age", 30)
));
|
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.
Argumentsname | 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 | 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 TypeService Permission RequiredEdit automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Service",
"service_type": "incoming_message_webhook",
"config": {
"url": "https://your-company.example.com/webhook",
"secret": "abcdefg123"
},
"vars": {
"example": 42
},
"active": true
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->createService([
'name' => "Example Service",
'service_type' => "incoming_message_webhook",
'config' => ['url' => "https://your-company.example.com/webhook", 'secret' => "abcdefg123"],
'vars' => ['example' => 42],
'active' => true
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.createService(
name = "Example Service",
service_type = "incoming_message_webhook",
config = {'url': "https://your-company.example.com/webhook", 'secret': "abcdefg123"},
vars = {'example': 42},
active = True
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.create_service({
'name' => "Example Service",
'service_type' => "incoming_message_webhook",
'config' => {'url' => "https://your-company.example.com/webhook", 'secret' => "abcdefg123"},
'vars' => {'example' => 42},
'active' => true
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.createService({
name: "Example Service",
service_type: "incoming_message_webhook",
config: {'url': "https://your-company.example.com/webhook", 'secret': "abcdefg123"},
vars: {'example': 42},
active: true
}, function(err, service) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.createService(Util.options(
"name", "Example Service",
"service_type", "incoming_message_webhook",
"config", Util.options("url", "https://your-company.example.com/webhook", "secret", "abcdefg123"),
"vars", Util.options("example", 42),
"active", true
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = await project.CreateServiceAsync(Util.Options(
"name", "Example Service",
"service_type", "incoming_message_webhook",
"config", Util.Options("url", "https://your-company.example.com/webhook", "secret", "abcdefg123"),
"vars", Util.Options("example", 42),
"active", true
));
|
Query services
GET /v1/projects/<project_id>/services Queries services within the given project.
Argumentsname | string, optional 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 TypeRaw API: Query result of Service Permission RequiredView automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services?active=1&context=message"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryServices([
'active' => true,
'context' => "message"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$service = $cursor->next();
// do something with $service
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryServices(
active = True,
context = "message"
)
for service in cursor.limit(50):
# do something with service
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_services({
'active' => true,
'context' => "message"
})
cursor.limit(50).each { |service|
# do something with service
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryServices({
active: true,
context: "message"
});
cursor.limit(50).each(function(err, service) {
if (err) {
// do something with err
}
if (service) {
// do something with service
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Service> cursor = project.queryServices(Util.options(
"active", true,
"context", "message"
));
cursor.limit(50);
while (cursor.hasNext()) {
Service service = cursor.next();
// do something with service
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Service> cursor = project.QueryServices(Util.Options(
"active", true,
"context", "message"
));
List<Service> list = await query.Limit(50).AllAsync();
foreach (Service service in list) {
// do something with service
}
|
Get service by ID
GET /v1/projects/<project_id>/services/<service_id> Retrieves the service with the given ID.
ArgumentsNone Return TypeService Permission RequiredView automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->getServiceById($service_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.getServiceById(service_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.get_service_by_id(service_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getServiceById(service_id, function(err, service) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.getServiceById(service_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = await project.GetServiceByIdAsync(service_id);
|
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.
ArgumentsReturn Typeobject Permission RequiredEdit automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/config" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-company.example.com/webhook",
"secret": "asdf123"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$service->setConfig(['url' => "https://your-company.example.com/webhook", 'secret' => "asdf123"]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
service.setConfig({'url': "https://your-company.example.com/webhook", 'secret': "asdf123"})
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
service.set_config({'url' => "https://your-company.example.com/webhook", 'secret' => "asdf123"})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
service.setConfig({'url': "https://your-company.example.com/webhook", 'secret': "asdf123"}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
service.setConfig(Util.options("url", "https://your-company.example.com/webhook", "secret", "asdf123"));
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
await service.SetConfigAsync(Util.Options("url", "https://your-company.example.com/webhook", "secret", "asdf123"));
|
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.
ArgumentsNone Return Typeobject Permission RequiredView automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/config"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$service->getConfig();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
service.getConfig()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
service.get_config()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
service.getConfig(function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
service.getConfig();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
await service.GetConfigAsync();
|
Update service details
POST /v1/projects/<project_id>/services/<service_id> Updates writable fields on the given service.
Argumentsname | string, optional | 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 | 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 TypeClient libraries: undefined Raw API: Service Permission RequiredEdit automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Poll Service",
"active": true,
"priority": 1,
"vars": {
"foo": "bar",
"baz": 42
},
"response_table_id": "DTf9fe14d9c306aed9"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$service->name = "Poll Service";
$service->active = true;
$service->priority = 1;
$service->vars->foo = "bar";
$service->vars->baz = 42;
$service->response_table_id = "DTf9fe14d9c306aed9";
$service->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
service.name = "Poll Service"
service.active = True
service.priority = 1
service.vars.foo = "bar"
service.vars.baz = 42
service.response_table_id = "DTf9fe14d9c306aed9"
service.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
service.name = "Poll Service"
service.active = true
service.priority = 1
service.vars.foo = "bar"
service.vars.baz = 42
service.response_table_id = "DTf9fe14d9c306aed9"
service.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
service.name = "Poll Service";
service.active = true;
service.priority = 1;
service.vars.foo = "bar";
service.vars.baz = 42;
service.response_table_id = "DTf9fe14d9c306aed9";
service.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
service.setName("Poll Service");
service.setActive(true);
service.setPriority(1);
service.vars().set("foo", "bar");
service.vars().set("baz", 42);
service.setResponseTableId("DTf9fe14d9c306aed9");
service.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
service.Name = "Poll Service";
service.Active = true;
service.Priority = 1;
service.Vars.Set("foo", "bar");
service.Vars.Set("baz", 42);
service.ResponseTableId = "DTf9fe14d9c306aed9";
await service.SaveAsync();
|
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.
Argumentsservice_id | Filter logs generated by a particular service
| message_id | Filter service logs related to a particular message
| contact_id | 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 TypeClient libraries: APICursor of object Returned Item Propertiestime_created |
UNIX timestamp
The time when the log entry was created
| content |
string
| 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 RequiredView automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/service_logs?execution_stats=1"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryServiceLogs([
'execution_stats' => true
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$obj = $cursor->next();
// do something with $obj
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryServiceLogs(
execution_stats = True
)
for obj in cursor.limit(50):
# do something with obj
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_service_logs({
'execution_stats' => true
})
cursor.limit(50).each { |obj|
# do something with obj
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryServiceLogs({
execution_stats: true
});
cursor.limit(50).each(function(err, obj) {
if (err) {
// do something with err
}
if (obj) {
// do something with obj
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<JSONObject> cursor = project.queryServiceLogs(Util.options(
"execution_stats", true
));
cursor.limit(50);
while (cursor.hasNext()) {
JSONObject obj = cursor.next();
// do something with obj
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<JObject> cursor = project.QueryServiceLogs(Util.Options(
"execution_stats", true
));
List<Array> list = await query.Limit(50).AllAsync();
foreach (JObject obj in list) {
// do something with obj
}
|
Query contacts' states for a service
GET /v1/projects/<project_id>/services/<service_id>/states Query the current states of contacts for this service.
Argumentsid | string, optional 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 TypeRaw API: Query result of ContactServiceState Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/states?id=q1"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$cursor = $service->queryContactStates([
'id' => "q1"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$state = $cursor->next();
// do something with $state
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
cursor = service.queryContactStates(
id = "q1"
)
for state in cursor.limit(50):
# do something with state
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
cursor = service.query_contact_states({
'id' => "q1"
})
cursor.limit(50).each { |state|
# do something with state
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
cursor = service.queryContactStates({
id: "q1"
});
cursor.limit(50).each(function(err, state) {
if (err) {
// do something with err
}
if (state) {
// do something with state
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
APICursor<ContactServiceState> cursor = service.queryContactStates(Util.options(
"id", "q1"
));
cursor.limit(50);
while (cursor.hasNext()) {
ContactServiceState state = cursor.next();
// do something with state
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
APICursor<ContactServiceState> cursor = service.QueryContactStates(Util.Options(
"id", "q1"
));
List<ContactServiceState> list = await query.Limit(50).AllAsync();
foreach (ContactServiceState state in list) {
// do something with state
}
|
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.
ArgumentsNone Return TypeContactServiceState Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/states/CONTACT_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$contact = $project->initContactById($contact_id);
$state = $service->getContactState($contact);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
contact = project.initContactById(contact_id)
state = service.getContactState(contact)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
contact = project.init_contact_by_id(contact_id)
state = service.get_contact_state(contact)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
var contact = project.initContactById(contact_id);
service.getContactState(contact, function(err, state) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.ContactServiceState;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
Contact contact = project.initContactById(contact_id);
ContactServiceState state = service.getContactState(contact);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
Contact contact = project.InitContactById(contact_id);
ContactServiceState state = await service.GetContactStateAsync(contact);
|
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.
Argumentsid | 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 TypeContactServiceState Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/states/CONTACT_ID" \
-H "Content-Type: application/json" \
-d '{
"id": "q1",
"vars": {
"foo": "bar"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$contact = $project->initContactById($contact_id);
$state = $service->setContactState($contact, [
'id' => "q1",
'vars' => ['foo' => "bar"]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
contact = project.initContactById(contact_id)
state = service.setContactState(contact,
id = "q1",
vars = {'foo': "bar"}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
contact = project.init_contact_by_id(contact_id)
state = service.set_contact_state(contact, {
'id' => "q1",
'vars' => {'foo' => "bar"}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
var contact = project.initContactById(contact_id);
service.setContactState(contact, {
id: "q1",
vars: {'foo': "bar"}
}, function(err, state) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.ContactServiceState;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
Contact contact = project.initContactById(contact_id);
ContactServiceState state = service.setContactState(contact, Util.options(
"id", "q1",
"vars", Util.options("foo", "bar")
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
Contact contact = project.InitContactById(contact_id);
ContactServiceState state = await service.SetContactStateAsync(contact, Util.Options(
"id", "q1",
"vars", Util.Options("foo", "bar")
));
|
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.
ArgumentsNone Return TypeContactServiceState Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID/states/CONTACT_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$contact = $project->initContactById($contact_id);
$state = $service->resetContactState($contact);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
contact = project.initContactById(contact_id)
state = service.resetContactState(contact)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
contact = project.init_contact_by_id(contact_id)
state = service.reset_contact_state(contact)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
var contact = project.initContactById(contact_id);
service.resetContactState(contact, function(err, state) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.ContactServiceState;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
Contact contact = project.initContactById(contact_id);
ContactServiceState state = service.resetContactState(contact);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
Contact contact = project.InitContactById(contact_id);
ContactServiceState state = await service.ResetContactStateAsync(contact);
|
Delete a service
DELETE /v1/projects/<project_id>/services/<service_id> ArgumentsNone Return Typeundefined Permission RequiredEdit automated services | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/services/SERVICE_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$service = $project->initServiceById($service_id);
$service->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
service = project.initServiceById(service_id)
service.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
service = project.init_service_by_id(service_id)
service.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var service = project.initServiceById(service_id);
service.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Service;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Service service = project.initServiceById(service_id);
service.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Service service = project.InitServiceById(service_id);
await service.DeleteAsync();
|
Labels | |
Object Type: Label
Represents a label used to organize messages within Telerivet.
Attributesid |
string, max 34 characters | read-only |
name |
string | 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 |
ID of the project this label belongs to
| read-only |
|
ExampleTelerivet_Label JSON: Label JSON: Telerivet::Label JSON: Label JSON: Label JSON: Label JSON: {
"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.
Argumentsname | string, optional 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 TypeRaw API: Query result of Label Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryLabels();
$cursor->limit(50);
while ($cursor->hasNext()) {
$label = $cursor->next();
// do something with $label
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryLabels()
for label in cursor.limit(50):
# do something with label
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_labels()
cursor.limit(50).each { |label|
# do something with label
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryLabels();
cursor.limit(50).each(function(err, label) {
if (err) {
// do something with err
}
if (label) {
// do something with label
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Label> cursor = project.queryLabels();
cursor.limit(50);
while (cursor.hasNext()) {
Label label = cursor.next();
// do something with label
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Label> cursor = project.QueryLabels();
List<Label> list = await query.Limit(50).AllAsync();
foreach (Label label in list) {
// do something with label
}
|
Create or retrieve a label by name
POST /v1/projects/<project_id>/labels Gets or creates a label by name.
ArgumentsReturn TypeLabel Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels" \
-H "Content-Type: application/json" \
-d '{
"name": "Important"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$label = $project->getOrCreateLabel("Important");
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
label = project.getOrCreateLabel("Important")
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
label = project.get_or_create_label("Important")
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getOrCreateLabel("Important", function(err, label) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Label;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Label label = project.getOrCreateLabel("Important");
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Label label = await project.GetOrCreateLabelAsync("Important");
|
Get label by ID
GET /v1/projects/<project_id>/labels/<label_id> Retrieves the label with the given ID.
ArgumentsNone Return TypeLabel Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels/LABEL_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$label = $project->getLabelById($label_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
label = project.getLabelById(label_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
label = project.get_label_by_id(label_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getLabelById(label_id, function(err, label) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Label;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Label label = project.getLabelById(label_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Label label = await project.GetLabelByIdAsync(label_id);
|
Query messages with a label
GET /v1/projects/<project_id>/labels/<label_id>/messages Queries messages with the given label.
Argumentsdirection | 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 | 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 | ID of the broadcast containing the message
Allowed Modifiers: broadcast_id[ne], broadcast_id[exists] (?) | scheduled_id | 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 TypeRaw API: Query result of Message Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels/LABEL_ID/messages?direction=incoming&message_type=sms"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$label = $project->initLabelById($label_id);
$cursor = $label->queryMessages([
'direction' => "incoming",
'message_type' => "sms"
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$message = $cursor->next();
// do something with $message
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
label = project.initLabelById(label_id)
cursor = label.queryMessages(
direction = "incoming",
message_type = "sms"
)
for message in cursor.limit(50):
# do something with message
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
label = project.init_label_by_id(label_id)
cursor = label.query_messages({
'direction' => "incoming",
'message_type' => "sms"
})
cursor.limit(50).each { |message|
# do something with message
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var label = project.initLabelById(label_id);
cursor = label.queryMessages({
direction: "incoming",
message_type: "sms"
});
cursor.limit(50).each(function(err, message) {
if (err) {
// do something with err
}
if (message) {
// do something with message
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Label;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Label label = project.initLabelById(label_id);
APICursor<Message> cursor = label.queryMessages(Util.options(
"direction", "incoming",
"message_type", "sms"
));
cursor.limit(50);
while (cursor.hasNext()) {
Message message = cursor.next();
// do something with message
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Label label = project.InitLabelById(label_id);
APICursor<Message> cursor = label.QueryMessages(Util.Options(
"direction", "incoming",
"message_type", "sms"
));
List<Message> list = await query.Limit(50).AllAsync();
foreach (Message message in list) {
// do something with message
}
|
Update label details
POST /v1/projects/<project_id>/labels/<label_id> Updates writable fields on the given label.
Argumentsname | string, optional | 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 TypeClient libraries: undefined Raw API: Label Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels/LABEL_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Important",
"vars": {
"foo": "bar",
"baz": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$label = $project->initLabelById($label_id);
$label->name = "Important";
$label->vars->foo = "bar";
$label->vars->baz = 42;
$label->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
label = project.initLabelById(label_id)
label.name = "Important"
label.vars.foo = "bar"
label.vars.baz = 42
label.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
label = project.init_label_by_id(label_id)
label.name = "Important"
label.vars.foo = "bar"
label.vars.baz = 42
label.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var label = project.initLabelById(label_id);
label.name = "Important";
label.vars.foo = "bar";
label.vars.baz = 42;
label.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Label;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Label label = project.initLabelById(label_id);
label.setName("Important");
label.vars().set("foo", "bar");
label.vars().set("baz", 42);
label.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Label label = project.InitLabelById(label_id);
label.Name = "Important";
label.Vars.Set("foo", "bar");
label.Vars.Set("baz", 42);
await label.SaveAsync();
|
Delete a label
DELETE /v1/projects/<project_id>/labels/<label_id> Deletes the given label (Note: no messages are deleted.)
ArgumentsNone Return Typeundefined Permission RequiredSend messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/labels/LABEL_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$label = $project->initLabelById($label_id);
$label->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
label = project.initLabelById(label_id)
label.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
label = project.init_label_by_id(label_id)
label.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var label = project.initLabelById(label_id);
label.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Label;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Label label = project.initLabelById(label_id);
label.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Label label = project.InitLabelById(label_id);
await label.DeleteAsync();
|
Groups | |
Object Type: Group
Represents a group used to organize contacts within Telerivet.
Attributesid |
string, max 34 characters | read-only |
name |
string | 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 |
ID of the project this group belongs to
| read-only |
|
ExampleTelerivet_Group JSON: Group JSON: Telerivet::Group JSON: Group JSON: Group JSON: Group JSON: {
"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.
Argumentsname | string, optional 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 TypeRaw API: Query result of Group Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryGroups();
$cursor->limit(50);
while ($cursor->hasNext()) {
$group = $cursor->next();
// do something with $group
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryGroups()
for group in cursor.limit(50):
# do something with group
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_groups()
cursor.limit(50).each { |group|
# do something with group
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryGroups();
cursor.limit(50).each(function(err, group) {
if (err) {
// do something with err
}
if (group) {
// do something with group
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<Group> cursor = project.queryGroups();
cursor.limit(50);
while (cursor.hasNext()) {
Group group = cursor.next();
// do something with group
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<Group> cursor = project.QueryGroups();
List<Group> list = await query.Limit(50).AllAsync();
foreach (Group group in list) {
// do something with group
}
|
Create or retrieve a group by name
POST /v1/projects/<project_id>/groups Retrieves or creates a group by name.
ArgumentsReturn TypeGroup Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups" \
-H "Content-Type: application/json" \
-d '{
"name": "Subscribers"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$group = $project->getOrCreateGroup("Subscribers");
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
group = project.getOrCreateGroup("Subscribers")
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
group = project.get_or_create_group("Subscribers")
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getOrCreateGroup("Subscribers", function(err, group) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Group;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Group group = project.getOrCreateGroup("Subscribers");
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Group group = await project.GetOrCreateGroupAsync("Subscribers");
|
Get group by ID
GET /v1/projects/<project_id>/groups/<group_id> Retrieves the group with the given ID.
ArgumentsNone Return TypeGroup Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$group = $project->getGroupById($group_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
group = project.getGroupById(group_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
group = project.get_group_by_id(group_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getGroupById(group_id, function(err, group) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Group;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Group group = project.getGroupById(group_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Group group = await project.GetGroupByIdAsync(group_id);
|
Query contacts in a group
GET /v1/projects/<project_id>/groups/<group_id>/contacts Queries contacts that are members of the given group.
Argumentsname | string, optional 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 TypeRaw API: Query result of Contact Permission RequiredView contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID/contacts?name[prefix]=John&last_message_time[min]=1733350916"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$group = $project->initGroupById($group_id);
$cursor = $group->queryContacts([
'name' => ['prefix' => "John"],
'last_message_time' => ['min' => 1733350916]
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$contact = $cursor->next();
// do something with $contact
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
group = project.initGroupById(group_id)
cursor = group.queryContacts(
name = {'prefix': "John"},
last_message_time = {'min': 1733350916}
)
for contact in cursor.limit(50):
# do something with contact
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
group = project.init_group_by_id(group_id)
cursor = group.query_contacts({
'name' => {'prefix' => "John"},
'last_message_time' => {'min' => 1733350916}
})
cursor.limit(50).each { |contact|
# do something with contact
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var group = project.initGroupById(group_id);
cursor = group.queryContacts({
name: {'prefix': "John"},
last_message_time: {'min': 1733350916}
});
cursor.limit(50).each(function(err, contact) {
if (err) {
// do something with err
}
if (contact) {
// do something with contact
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Group;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Group group = project.initGroupById(group_id);
APICursor<Contact> cursor = group.queryContacts(Util.options(
"name", Util.options("prefix", "John"),
"last_message_time", Util.options("min", 1733350916)
));
cursor.limit(50);
while (cursor.hasNext()) {
Contact contact = cursor.next();
// do something with contact
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Group group = project.InitGroupById(group_id);
APICursor<Contact> cursor = group.QueryContacts(Util.Options(
"name", Util.Options("prefix", "John"),
"last_message_time", Util.Options("min", 1733350916)
));
List<Contact> list = await query.Limit(50).AllAsync();
foreach (Contact contact in list) {
// do something with contact
}
|
Query scheduled messages to a group
GET /v1/projects/<project_id>/groups/<group_id>/scheduled Queries scheduled messages to the given group.
Argumentsmessage_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 | 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 TypeRaw API: Query result of ScheduledMessage Permission RequiredView messages | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID/scheduled?message_type=sms&next_time[min]=1741126916"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$group = $project->initGroupById($group_id);
$cursor = $group->queryScheduledMessages([
'message_type' => "sms",
'next_time' => ['min' => 1741126916]
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$scheduled_msg = $cursor->next();
// do something with $scheduled_msg
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
group = project.initGroupById(group_id)
cursor = group.queryScheduledMessages(
message_type = "sms",
next_time = {'min': 1741126916}
)
for scheduled_msg in cursor.limit(50):
# do something with scheduled_msg
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
group = project.init_group_by_id(group_id)
cursor = group.query_scheduled_messages({
'message_type' => "sms",
'next_time' => {'min' => 1741126916}
})
cursor.limit(50).each { |scheduled_msg|
# do something with scheduled_msg
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var group = project.initGroupById(group_id);
cursor = group.queryScheduledMessages({
message_type: "sms",
next_time: {'min': 1741126916}
});
cursor.limit(50).each(function(err, scheduled_msg) {
if (err) {
// do something with err
}
if (scheduled_msg) {
// do something with scheduled_msg
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Group;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Group group = project.initGroupById(group_id);
APICursor<ScheduledMessage> cursor = group.queryScheduledMessages(Util.options(
"message_type", "sms",
"next_time", Util.options("min", 1741126916)
));
cursor.limit(50);
while (cursor.hasNext()) {
ScheduledMessage scheduled_msg = cursor.next();
// do something with scheduled_msg
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Group group = project.InitGroupById(group_id);
APICursor<ScheduledMessage> cursor = group.QueryScheduledMessages(Util.Options(
"message_type", "sms",
"next_time", Util.Options("min", 1741126916)
));
List<ScheduledMessage> list = await query.Limit(50).AllAsync();
foreach (ScheduledMessage scheduled_msg in list) {
// do something with scheduled_msg
}
|
Update group details
POST /v1/projects/<project_id>/groups/<group_id> Updates writable fields on the given group.
Argumentsname | string, optional | 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 TypeClient libraries: undefined Raw API: Group Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Subscribers",
"add_time_variable": "subscription_time",
"vars": {
"foo": "bar",
"baz": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$group = $project->initGroupById($group_id);
$group->name = "Subscribers";
$group->add_time_variable = "subscription_time";
$group->vars->foo = "bar";
$group->vars->baz = 42;
$group->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
group = project.initGroupById(group_id)
group.name = "Subscribers"
group.add_time_variable = "subscription_time"
group.vars.foo = "bar"
group.vars.baz = 42
group.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
group = project.init_group_by_id(group_id)
group.name = "Subscribers"
group.add_time_variable = "subscription_time"
group.vars.foo = "bar"
group.vars.baz = 42
group.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var group = project.initGroupById(group_id);
group.name = "Subscribers";
group.add_time_variable = "subscription_time";
group.vars.foo = "bar";
group.vars.baz = 42;
group.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Group;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Group group = project.initGroupById(group_id);
group.setName("Subscribers");
group.setAddTimeVariable("subscription_time");
group.vars().set("foo", "bar");
group.vars().set("baz", 42);
group.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Group group = project.InitGroupById(group_id);
group.Name = "Subscribers";
group.AddTimeVariable = "subscription_time";
group.Vars.Set("foo", "bar");
group.Vars.Set("baz", 42);
await group.SaveAsync();
|
Delete a group
DELETE /v1/projects/<project_id>/groups/<group_id> Deletes this group (Note: no contacts are deleted.)
ArgumentsNone Return Typeundefined Permission RequiredEdit contacts | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/groups/GROUP_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$group = $project->initGroupById($group_id);
$group->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
group = project.initGroupById(group_id)
group.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
group = project.init_group_by_id(group_id)
group.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var group = project.initGroupById(group_id);
group.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Group;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
Group group = project.initGroupById(group_id);
group.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
Group group = project.InitGroupById(group_id);
await group.DeleteAsync();
|
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.
Attributesid |
string, max 34 characters | read-only |
name |
string | 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 |
ID of the project this data table belongs to
| read-only |
|
ExampleTelerivet_DataTable JSON: DataTable JSON: Telerivet::DataTable JSON: DataTable JSON: DataTable JSON: DataTable JSON: {
"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.
Attributesid |
string, max 34 characters | read-only |
contact_id |
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 |
ID of the table this data row belongs to
| read-only |
project_id |
ID of the project this data row belongs to
| read-only |
|
ExampleTelerivet_DataRow JSON: DataRow JSON: Telerivet::DataRow JSON: DataRow JSON: DataRow JSON: DataRow JSON: {
"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.
ArgumentsReturn TypeDataTable Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables" \
-H "Content-Type: application/json" \
-d '{
"name": "Election Reports"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->getOrCreateDataTable("Election Reports");
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.getOrCreateDataTable("Election Reports")
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.get_or_create_data_table("Election Reports")
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getOrCreateDataTable("Election Reports", function(err, table) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.getOrCreateDataTable("Election Reports");
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = await project.GetOrCreateDataTableAsync("Election Reports");
|
Get data table by ID
GET /v1/projects/<project_id>/tables/<table_id> Retrieves the data table with the given ID.
ArgumentsNone Return TypeDataTable Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->getDataTableById($table_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.getDataTableById(table_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.get_data_table_by_id(table_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getDataTableById(table_id, function(err, table) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.getDataTableById(table_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = await project.GetDataTableByIdAsync(table_id);
|
Query rows in a data table
GET /v1/projects/<project_id>/tables/<table_id>/rows Queries rows in this data table.
Argumentstime_created | UNIX timestamp, optional Filter data rows by the time they were created
Allowed Modifiers: time_created[min], time_created[max] (?) | contact_id | 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 TypeRaw API: Query result of DataRow Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/rows?vars[q1]=yes&vars[q2]=no"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$cursor = $table->queryRows([
'vars' => ['q1' => "yes", 'q2' => "no"]
]);
$cursor->limit(50);
while ($cursor->hasNext()) {
$row = $cursor->next();
// do something with $row
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
cursor = table.queryRows(
vars = {'q1': "yes", 'q2': "no"}
)
for row in cursor.limit(50):
# do something with row
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
cursor = table.query_rows({
'vars' => {'q1' => "yes", 'q2' => "no"}
})
cursor.limit(50).each { |row|
# do something with row
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
cursor = table.queryRows({
vars: {'q1': "yes", 'q2': "no"}
});
cursor.limit(50).each(function(err, row) {
if (err) {
// do something with err
}
if (row) {
// do something with row
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
APICursor<DataRow> cursor = table.queryRows(Util.options(
"vars", Util.options("q1", "yes", "q2", "no")
));
cursor.limit(50);
while (cursor.hasNext()) {
DataRow row = cursor.next();
// do something with row
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
APICursor<DataRow> cursor = table.QueryRows(Util.Options(
"vars", Util.Options("q1", "yes", "q2", "no")
));
List<DataRow> list = await query.Limit(50).AllAsync();
foreach (DataRow row in list) {
// do something with row
}
|
Add new data row
POST /v1/projects/<project_id>/tables/<table_id>/rows Adds a new row to this data table.
Argumentscontact_id | 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 TypeDataRow Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/rows" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+16505550123",
"vars": {
"q1": "yes",
"q2": "no"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$row = $table->createRow([
'from_number' => "+16505550123",
'vars' => ['q1' => "yes", 'q2' => "no"]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
row = table.createRow(
from_number = "+16505550123",
vars = {'q1': "yes", 'q2': "no"}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
row = table.create_row({
'from_number' => "+16505550123",
'vars' => {'q1' => "yes", 'q2' => "no"}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.createRow({
from_number: "+16505550123",
vars: {'q1': "yes", 'q2': "no"}
}, function(err, row) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.DataRow;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
DataRow row = table.createRow(Util.options(
"from_number", "+16505550123",
"vars", Util.options("q1", "yes", "q2", "no")
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
DataRow row = await table.CreateRowAsync(Util.Options(
"from_number", "+16505550123",
"vars", Util.Options("q1", "yes", "q2", "no")
));
|
Update data row
POST /v1/projects/<project_id>/tables/<table_id>/rows/<row_id> Updates writable fields on the given data data row.
Argumentscontact_id | 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 TypeClient libraries: undefined Raw API: DataRow Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/rows/ROW_ID" \
-H "Content-Type: application/json" \
-d '{
"contact_id": "CTa1299c3d0e371023",
"from_number": "+16505550123",
"vars": {
"q1": "yes",
"q2": "no"
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$row = $table->initRowById($row_id);
$row->contact_id = "CTa1299c3d0e371023";
$row->from_number = "+16505550123";
$row->vars->q1 = "yes";
$row->vars->q2 = "no";
$row->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
row = table.initRowById(row_id)
row.contact_id = "CTa1299c3d0e371023"
row.from_number = "+16505550123"
row.vars.q1 = "yes"
row.vars.q2 = "no"
row.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
row = table.init_row_by_id(row_id)
row.contact_id = "CTa1299c3d0e371023"
row.from_number = "+16505550123"
row.vars.q1 = "yes"
row.vars.q2 = "no"
row.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
var row = table.initRowById(row_id);
row.contact_id = "CTa1299c3d0e371023";
row.from_number = "+16505550123";
row.vars.q1 = "yes";
row.vars.q2 = "no";
row.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataRow;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
DataRow row = table.initRowById(row_id);
row.setContactId("CTa1299c3d0e371023");
row.setFromNumber("+16505550123");
row.vars().set("q1", "yes");
row.vars().set("q2", "no");
row.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
DataRow row = table.InitRowById(row_id);
row.ContactId = "CTa1299c3d0e371023";
row.FromNumber = "+16505550123";
row.Vars.Set("q1", "yes");
row.Vars.Set("q2", "no");
await row.SaveAsync();
|
Delete data row
DELETE /v1/projects/<project_id>/tables/<table_id>/rows/<row_id> ArgumentsNone Return Typeundefined Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/rows/ROW_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$row = $table->initRowById($row_id);
$row->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
row = table.initRowById(row_id)
row.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
row = table.init_row_by_id(row_id)
row.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
var row = table.initRowById(row_id);
row.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataRow;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
DataRow row = table.initRowById(row_id);
row.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
DataRow row = table.InitRowById(row_id);
await row.DeleteAsync();
|
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.
ArgumentsNone Return TypeDataRow Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/rows/ROW_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$row = $table->getRowById($row_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
row = table.getRowById(row_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
row = table.get_row_by_id(row_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.getRowById(row_id, function(err, row) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataRow;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
DataRow row = table.getRowById(row_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
DataRow row = await table.GetRowByIdAsync(row_id);
|
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.)
ArgumentsNone Return Typearray Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/fields"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$table->getFields();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
table.getFields()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
table.get_fields()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.getFields(function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
table.getFields();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
await table.GetFieldsAsync();
|
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.
Argumentsname | string, max 64 characters, optional Display name for the field
| type | string, optional 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 Typeobject Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/fields/VARIABLE" \
-H "Content-Type: application/json" \
-d '{
"name": "Question 1",
"type": "number",
"order": 2
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$table->setFieldMetadata("q1", [
'name' => "Question 1",
'type' => "number",
'order' => 2
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
table.setFieldMetadata("q1",
name = "Question 1",
type = "number",
order = 2
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
table.set_field_metadata("q1", {
'name' => "Question 1",
'type' => "number",
'order' => 2
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.setFieldMetadata("q1", {
name: "Question 1",
type: "number",
order: 2
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
table.setFieldMetadata("q1", Util.options(
"name", "Question 1",
"type", "number",
"order", 2
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
await table.SetFieldMetadataAsync("q1", Util.Options(
"name", "Question 1",
"type", "number",
"order", 2
));
|
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}
Argumentsvariable | string, required Variable of field to count by.
|
Return Typeobject Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID/count_rows_by_value?variable=q1_code"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$table->countRowsByValue("q1_code");
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
table.countRowsByValue("q1_code")
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
table.count_rows_by_value("q1_code")
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.countRowsByValue("q1_code", function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
table.countRowsByValue("q1_code");
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
await table.CountRowsByValueAsync("q1_code");
|
Update table details
POST /v1/projects/<project_id>/tables/<table_id> Updates writable fields on the given data table.
Argumentsname | string, optional | 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 TypeClient libraries: undefined Raw API: DataTable Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Poll Responses",
"show_add_row": false,
"show_stats": true,
"show_contact_columns": true,
"vars": {
"foo": "bar",
"baz": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$table->name = "Poll Responses";
$table->show_add_row = false;
$table->show_stats = true;
$table->show_contact_columns = true;
$table->vars->foo = "bar";
$table->vars->baz = 42;
$table->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
table.name = "Poll Responses"
table.show_add_row = False
table.show_stats = True
table.show_contact_columns = True
table.vars.foo = "bar"
table.vars.baz = 42
table.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
table.name = "Poll Responses"
table.show_add_row = false
table.show_stats = true
table.show_contact_columns = true
table.vars.foo = "bar"
table.vars.baz = 42
table.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.name = "Poll Responses";
table.show_add_row = false;
table.show_stats = true;
table.show_contact_columns = true;
table.vars.foo = "bar";
table.vars.baz = 42;
table.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
table.setName("Poll Responses");
table.setShowAddRow(false);
table.setShowStats(true);
table.setShowContactColumns(true);
table.vars().set("foo", "bar");
table.vars().set("baz", 42);
table.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
table.Name = "Poll Responses";
table.ShowAddRow = false;
table.ShowStats = true;
table.ShowContactColumns = true;
table.Vars.Set("foo", "bar");
table.Vars.Set("baz", 42);
await table.SaveAsync();
|
Delete a data table
DELETE /v1/projects/<project_id>/tables/<table_id> Permanently deletes the given data table, including all its rows
ArgumentsNone Return Typeundefined Permission RequiredEdit data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables/TABLE_ID" \
-X DELETE
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$table = $project->initDataTableById($table_id);
$table->delete();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
table = project.initDataTableById(table_id)
table.delete()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
table = project.init_data_table_by_id(table_id)
table.delete()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
var table = project.initDataTableById(table_id);
table.delete(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.DataTable;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
DataTable table = project.initDataTableById(table_id);
table.delete();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
DataTable table = project.InitDataTableById(table_id);
await table.DeleteAsync();
|
Query data tables
GET /v1/projects/<project_id>/tables Queries data tables within the given project.
Argumentsname | 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 TypeRaw API: Query result of DataTable Permission RequiredView data tables | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/tables"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryDataTables();
$cursor->limit(50);
while ($cursor->hasNext()) {
$table = $cursor->next();
// do something with $table
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryDataTables()
for table in cursor.limit(50):
# do something with table
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_data_tables()
cursor.limit(50).each { |table|
# do something with table
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryDataTables();
cursor.limit(50).each(function(err, table) {
if (err) {
// do something with err
}
if (table) {
// do something with table
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<DataTable> cursor = project.queryDataTables();
cursor.limit(50);
while (cursor.hasNext()) {
DataTable table = cursor.next();
// do something with table
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<DataTable> cursor = project.QueryDataTables();
List<DataTable> list = await query.Limit(50).AllAsync();
foreach (DataTable table in list) {
// do something with table
}
|
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.
Attributesid |
string, max 34 characters | read-only |
name |
string | updatable |
timezone_id |
string | 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 |
ID of the organization this project belongs to
| read-only |
|
ExampleTelerivet_Project JSON: Project JSON: Telerivet::Project JSON: Project JSON: Project JSON: Project JSON: {
"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.
Argumentsname | string, required Name of the project to create, which must be unique in the organization.
| timezone_id | string, optional | 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 TypeProject Permission RequiredEdit project settings | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations/ORGANIZATION_ID/projects" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Project",
"timezone_id": "America/Los_Angeles",
"url_slug": "asdf",
"vars": {
"example": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$organization = $tr->initOrganizationById($organization_id);
$project = $organization->createProject([
'name' => "Example Project",
'timezone_id' => "America/Los_Angeles",
'url_slug' => "asdf",
'vars' => ['example' => 42]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
organization = tr.initOrganizationById(organization_id)
project = organization.createProject(
name = "Example Project",
timezone_id = "America/Los_Angeles",
url_slug = "asdf",
vars = {'example': 42}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
organization = tr.init_organization_by_id(organization_id)
project = organization.create_project({
'name' => "Example Project",
'timezone_id' => "America/Los_Angeles",
'url_slug' => "asdf",
'vars' => {'example' => 42}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var organization = tr.initOrganizationById(organization_id);
organization.createProject({
name: "Example Project",
timezone_id: "America/Los_Angeles",
url_slug: "asdf",
vars: {'example': 42}
}, function(err, project) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
import com.telerivet.Organization;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.initOrganizationById(organization_id);
Project project = organization.createProject(Util.options(
"name", "Example Project",
"timezone_id", "America/Los_Angeles",
"url_slug", "asdf",
"vars", Util.options("example", 42)
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.InitOrganizationById(organization_id);
Project project = await organization.CreateProjectAsync(Util.Options(
"name", "Example Project",
"timezone_id", "America/Los_Angeles",
"url_slug", "asdf",
"vars", Util.Options("example", 42)
));
|
Get project by ID
GET /v1/projects/<project_id> Retrieves the Telerivet project with the given ID.
ArgumentsNone Return TypeProject | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->getProjectById($project_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.getProjectById(project_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.get_project_by_id(project_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
tr.getProjectById(project_id, function(err, project) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.getProjectById(project_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = await tr.GetProjectByIdAsync(project_id);
|
Query projects
GET /v1/projects Queries projects accessible to the current user account.
Argumentsname | string, optional 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 TypeRaw API: Query result of Project | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$cursor = $tr->queryProjects();
$cursor->limit(50);
while ($cursor->hasNext()) {
$project = $cursor->next();
// do something with $project
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
cursor = tr.queryProjects()
for project in cursor.limit(50):
# do something with project
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
cursor = tr.query_projects()
cursor.limit(50).each { |project|
# do something with project
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
cursor = tr.queryProjects();
cursor.limit(50).each(function(err, project) {
if (err) {
// do something with err
}
if (project) {
// do something with project
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
APICursor<Project> cursor = tr.queryProjects();
cursor.limit(50);
while (cursor.hasNext()) {
Project project = cursor.next();
// do something with project
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
APICursor<Project> cursor = tr.QueryProjects();
List<Project> list = await query.Limit(50).AllAsync();
foreach (Project project in list) {
// do something with project
}
|
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.)
ArgumentsNone Return Typearray Permission RequiredView user permissions | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/users"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->getUsers();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.getUsers()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.get_users()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getUsers(function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.getUsers();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.GetUsersAsync();
|
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.
Argumentsstart_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 Typeobject Return Value Propertiesintervals |
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 RequiredView statistics | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/message_stats?start_date=2022-01-01&end_date=2022-12-31&rollup=month&properties=phone_name%2Cstatus%2Cdirection&metrics=count%2Cnum_parts%2Cprice¤cy=USD&filters[direction]=outgoing&filters[source]=api"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->getMessageStats([
'start_date' => "2022-01-01",
'end_date' => "2022-12-31",
'rollup' => "month",
'properties' => "phone_name,status,direction",
'metrics' => "count,num_parts,price",
'currency' => "USD",
'filters' => ['direction' => "outgoing", 'source' => "api"]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.getMessageStats(
start_date = "2022-01-01",
end_date = "2022-12-31",
rollup = "month",
properties = "phone_name,status,direction",
metrics = "count,num_parts,price",
currency = "USD",
filters = {'direction': "outgoing", 'source': "api"}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.get_message_stats({
'start_date' => "2022-01-01",
'end_date' => "2022-12-31",
'rollup' => "month",
'properties' => "phone_name,status,direction",
'metrics' => "count,num_parts,price",
'currency' => "USD",
'filters' => {'direction' => "outgoing", 'source' => "api"}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getMessageStats({
start_date: "2022-01-01",
end_date: "2022-12-31",
rollup: "month",
properties: "phone_name,status,direction",
metrics: "count,num_parts,price",
currency: "USD",
filters: {'direction': "outgoing", 'source': "api"}
}, function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.getMessageStats(Util.options(
"start_date", "2022-01-01",
"end_date", "2022-12-31",
"rollup", "month",
"properties", "phone_name,status,direction",
"metrics", "count,num_parts,price",
"currency", "USD",
"filters", Util.options("direction", "outgoing", "source", "api")
));
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
await project.GetMessageStatsAsync(Util.Options(
"start_date", "2022-01-01",
"end_date", "2022-12-31",
"rollup", "month",
"properties", "phone_name,status,direction",
"metrics", "count,num_parts,price",
"currency", "USD",
"filters", Util.Options("direction", "outgoing", "source", "api")
));
|
Update project details
POST /v1/projects/<project_id> Updates writable fields on the given project.
Argumentsname | string, optional | timezone_id | string, optional | 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 TypeClient libraries: undefined Raw API: Project Permission RequiredEdit project settings | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Project",
"timezone_id": "America/Los_Angeles",
"url_slug": "asdf",
"auto_create_contacts": true,
"vars": {
"foo": "bar",
"baz": 42
}
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$project->name = "Example Project";
$project->timezone_id = "America/Los_Angeles";
$project->url_slug = "asdf";
$project->auto_create_contacts = true;
$project->vars->foo = "bar";
$project->vars->baz = 42;
$project->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
project.name = "Example Project"
project.timezone_id = "America/Los_Angeles"
project.url_slug = "asdf"
project.auto_create_contacts = True
project.vars.foo = "bar"
project.vars.baz = 42
project.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
project.name = "Example Project"
project.timezone_id = "America/Los_Angeles"
project.url_slug = "asdf"
project.auto_create_contacts = true
project.vars.foo = "bar"
project.vars.baz = 42
project.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.name = "Example Project";
project.timezone_id = "America/Los_Angeles";
project.url_slug = "asdf";
project.auto_create_contacts = true;
project.vars.foo = "bar";
project.vars.baz = 42;
project.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
project.setName("Example Project");
project.setTimezoneId("America/Los_Angeles");
project.setUrlSlug("asdf");
project.setAutoCreateContacts(true);
project.vars().set("foo", "bar");
project.vars().set("baz", 42);
project.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
project.Name = "Example Project";
project.TimezoneId = "America/Los_Angeles";
project.UrlSlug = "asdf";
project.AutoCreateContacts = true;
project.Vars.Set("foo", "bar");
project.Vars.Set("baz", 42);
await project.SaveAsync();
|
Airtime Transactions | |
Object Type: AirtimeTransaction
Attributesid |
string ID of the airtime transaction
| read-only |
to_number |
string Destination phone number in international format (no leading +)
| read-only |
operator_name |
string | read-only |
country |
string | 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 | read-only |
price |
string Price charged for airtime transaction, in units of price_currency
| read-only |
price_currency |
string | 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 |
|
ExampleTelerivet_AirtimeTransaction JSON: AirtimeTransaction JSON: Telerivet::AirtimeTransaction JSON: AirtimeTransaction JSON: AirtimeTransaction JSON: AirtimeTransaction JSON: {
"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.
Argumentstime_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 TypeRaw API: Query result of AirtimeTransaction Permission RequiredView airtime | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/airtime_transactions"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$cursor = $project->queryAirtimeTransactions();
$cursor->limit(50);
while ($cursor->hasNext()) {
$airtimetransaction = $cursor->next();
// do something with $airtimetransaction
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
cursor = project.queryAirtimeTransactions()
for airtimetransaction in cursor.limit(50):
# do something with airtimetransaction
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
cursor = project.query_airtime_transactions()
cursor.limit(50).each { |airtimetransaction|
# do something with airtimetransaction
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
cursor = project.queryAirtimeTransactions();
cursor.limit(50).each(function(err, airtimetransaction) {
if (err) {
// do something with err
}
if (airtimetransaction) {
// do something with airtimetransaction
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
APICursor<AirtimeTransaction> cursor = project.queryAirtimeTransactions();
cursor.limit(50);
while (cursor.hasNext()) {
AirtimeTransaction airtimetransaction = cursor.next();
// do something with airtimetransaction
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
APICursor<AirtimeTransaction> cursor = project.QueryAirtimeTransactions();
List<AirtimeTransaction> list = await query.Limit(50).AllAsync();
foreach (AirtimeTransaction airtimetransaction in list) {
// do something with airtimetransaction
}
|
Get airtime transaction by ID
GET /v1/projects/<project_id>/airtime_transactions/<airtimetransaction_id> Gets an airtime transaction by ID
ArgumentsNone Return TypeAirtimeTransaction Permission RequiredView airtime | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/projects/PROJECT_ID/airtime_transactions/AIRTIMETRANSACTION_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$project = $tr->initProjectById($project_id);
$airtimetransaction = $project->getAirtimeTransactionById($airtimetransaction_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
project = tr.initProjectById(project_id)
airtimetransaction = project.getAirtimeTransactionById(airtimetransaction_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
project = tr.init_project_by_id(project_id)
airtimetransaction = project.get_airtime_transaction_by_id(airtimetransaction_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var project = tr.initProjectById(project_id);
project.getAirtimeTransactionById(airtimetransaction_id, function(err, airtimetransaction) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.AirtimeTransaction;
import com.telerivet.Project;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.initProjectById(project_id);
AirtimeTransaction airtimetransaction = project.getAirtimeTransactionById(airtimetransaction_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Project project = tr.InitProjectById(project_id);
AirtimeTransaction airtimetransaction = await project.GetAirtimeTransactionByIdAsync(airtimetransaction_id);
|
Organizations | |
Object Type: Organization
Represents a Telerivet organization.
Attributesid |
string, max 34 characters | read-only |
name |
string | updatable |
timezone_id |
string | updatable |
|
ExampleTelerivet_Organization JSON: Organization JSON: Telerivet::Organization JSON: Organization JSON: Organization JSON: Organization JSON: {
"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.
ArgumentsNone Return TypeOrganization Permission RequiredAccess organization | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations/ORGANIZATION_ID"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$organization = $tr->getOrganizationById($organization_id);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
organization = tr.getOrganizationById(organization_id)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
organization = tr.get_organization_by_id(organization_id)
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
tr.getOrganizationById(organization_id, function(err, organization) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Organization;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.getOrganizationById(organization_id);
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = await tr.GetOrganizationByIdAsync(organization_id);
|
Query organizations
GET /v1/organizations Queries organizations accessible to the current user account.
Argumentsname | 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 TypeRaw API: Query result of Organization | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$cursor = $tr->queryOrganizations();
$cursor->limit(50);
while ($cursor->hasNext()) {
$organization = $cursor->next();
// do something with $organization
}
import telerivet
tr = telerivet.API(YOUR_API_KEY)
cursor = tr.queryOrganizations()
for organization in cursor.limit(50):
# do something with organization
pass
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
cursor = tr.query_organizations()
cursor.limit(50).each { |organization|
# do something with organization
}
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
cursor = tr.queryOrganizations();
cursor.limit(50).each(function(err, organization) {
if (err) {
// do something with err
}
if (organization) {
// do something with organization
}
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Util;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
APICursor<Organization> cursor = tr.queryOrganizations();
cursor.limit(50);
while (cursor.hasNext()) {
Organization organization = cursor.next();
// do something with organization
}
using Telerivet.Client;
using Newtonsoft.Json.Linq;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
APICursor<Organization> cursor = tr.QueryOrganizations();
List<Organization> list = await query.Limit(50).AllAsync();
foreach (Organization organization in list) {
// do something with organization
}
|
Update organization settings
POST /v1/organizations/<organization_id> Saves any fields that have changed for this organization.
Argumentsname | string, optional | timezone_id | string, optional |
Return TypeClient libraries: undefined Raw API: Organization Permission RequiredEdit organization settings | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations/ORGANIZATION_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Organization",
"timezone_id": "America/Los_Angeles"
}'
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$organization = $tr->initOrganizationById($organization_id);
$organization->name = "Example Organization";
$organization->timezone_id = "America/Los_Angeles";
$organization->save();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
organization = tr.initOrganizationById(organization_id)
organization.name = "Example Organization"
organization.timezone_id = "America/Los_Angeles"
organization.save()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
organization = tr.init_organization_by_id(organization_id)
organization.name = "Example Organization"
organization.timezone_id = "America/Los_Angeles"
organization.save()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var organization = tr.initOrganizationById(organization_id);
organization.name = "Example Organization";
organization.timezone_id = "America/Los_Angeles";
organization.save(function(err) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Organization;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.initOrganizationById(organization_id);
organization.setName("Example Organization");
organization.setTimezoneId("America/Los_Angeles");
organization.save();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.InitOrganizationById(organization_id);
organization.Name = "Example Organization";
organization.TimezoneId = "America/Los_Angeles";
await organization.SaveAsync();
|
Get billing details
GET /v1/organizations/<organization_id>/billing Retrieves information about the organization's service plan and account balance.
ArgumentsNone Return Typeobject Return Value Propertiesbalance |
string
| balance_currency |
string
Currency of prepaid account balance
| plan_name |
string
| plan_price |
string
| 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 RequiredView billing information | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations/ORGANIZATION_ID/billing"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$organization = $tr->initOrganizationById($organization_id);
$organization->getBillingDetails();
import telerivet
tr = telerivet.API(YOUR_API_KEY)
organization = tr.initOrganizationById(organization_id)
organization.getBillingDetails()
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
organization = tr.init_organization_by_id(organization_id)
organization.get_billing_details()
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var organization = tr.initOrganizationById(organization_id);
organization.getBillingDetails(function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Organization;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.initOrganizationById(organization_id);
organization.getBillingDetails();
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.InitOrganizationById(organization_id);
await organization.GetBillingDetailsAsync();
|
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 .
ArgumentsNone Return Typeint Permission RequiredView billing information | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations/ORGANIZATION_ID/usage/USAGE_TYPE"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$organization = $tr->initOrganizationById($organization_id);
$organization->getUsage("messages_day");
import telerivet
tr = telerivet.API(YOUR_API_KEY)
organization = tr.initOrganizationById(organization_id)
organization.getUsage("messages_day")
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
organization = tr.init_organization_by_id(organization_id)
organization.get_usage("messages_day")
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var organization = tr.initOrganizationById(organization_id);
organization.getUsage("messages_day", function(err, res) {
});
import com.telerivet.TelerivetAPI;
import com.telerivet.Organization;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.initOrganizationById(organization_id);
organization.getUsage("messages_day");
using Telerivet.Client;
...
TelerivetAPI tr = new TelerivetAPI(YOUR_API_KEY);
Organization organization = tr.InitOrganizationById(organization_id);
await organization.GetUsageAsync("messages_day");
|
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.
Argumentsstart_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 Typeobject Return Value Propertiesintervals |
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 RequiredView statistics | Examplecurl -s -u YOUR_API_KEY: \
"https://api.telerivet.com/v1/organizations/ORGANIZATION_ID/message_stats?start_date=2022-01-01&end_date=2022-12-31&rollup=month&properties=phone_name%2Cstatus%2Cdirection&metrics=count%2Cnum_parts%2Cprice¤cy=USD&filters[direction]=outgoing&filters[source]=api"
require_once 'path/to/telerivet.php';
$tr = new Telerivet_API($YOUR_API_KEY);
$organization = $tr->initOrganizationById($organization_id);
$organization->getMessageStats([
'start_date' => "2022-01-01",
'end_date' => "2022-12-31",
'rollup' => "month",
'properties' => "phone_name,status,direction",
'metrics' => "count,num_parts,price",
'currency' => "USD",
'filters' => ['direction' => "outgoing", 'source' => "api"]
]);
import telerivet
tr = telerivet.API(YOUR_API_KEY)
organization = tr.initOrganizationById(organization_id)
organization.getMessageStats(
start_date = "2022-01-01",
end_date = "2022-12-31",
rollup = "month",
properties = "phone_name,status,direction",
metrics = "count,num_parts,price",
currency = "USD",
filters = {'direction': "outgoing", 'source': "api"}
)
require 'telerivet'
tr = Telerivet::API.new(YOUR_API_KEY)
organization = tr.init_organization_by_id(organization_id)
organization.get_message_stats({
'start_date' => "2022-01-01",
'end_date' => "2022-12-31",
'rollup' => "month",
'properties' => "phone_name,status,direction",
'metrics' => "count,num_parts,price",
'currency' => "USD",
'filters' => {'direction' => "outgoing", 'source' => "api"}
})
var telerivet = require('telerivet');
var tr = new telerivet.API(YOUR_API_KEY);
var organization = tr.initOrganizationById(organization_id);
organization.getMessageStats({
start_date: "2022-01-01",
end_date: "2022-12-31",
rollup: "month",
properties: "phone_name,status,direction",
metrics: "count,nu |