telerivet v1.7.0
Node.js client library for Telerivet REST API
Overview
This library makes it easy to integrate your Node.js application with Telerivet. You can use it 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 automated services
- much more
All API methods are fully documented at https://telerivet.com/api/rest/node , as well as in the comments of the JS source files. To learn what functionality is available, start with lib/{telerivet.js,project.js,apicursor.js}.
System Requirements
Node.js 0.8 or higher
Installation
npm install telerivet
API Overview
First, import the telerivet module and create a telerivet.API
instance with your API key as a parameter:
var telerivet = require('telerivet');
var tr = new telerivet.API(API_KEY);
In order to access most API methods, you first need to get a Project
object:
var project = tr.initProjectById(PROJECT_ID);
When calling initProjectById
(and other init____ById
methods)
a "lazy" object is returned immediately, without making an API call to retrieve the
data for that object (e.g. project.name
).
To retrieve the data you can call getProjectById
instead:
tr.getProjectById(PROJECT_ID, function(err, project) {
if (err) throw err;
console.log(project.name);
});
Alternatively you can call load(callback)
after calling initProjectById
:
var project = tr.initProjectById(PROJECT_ID);
project.load(function(err, project) {
if (err) throw err;
console.log(project.name);
});
All methods that make an API request require a final callback parameter:
project.sendMessage({
to_number: '555-0001',
content: 'Hello world!'
}, function(err, message) {
if (err) throw err;
console.log(message);
});
The APICursor
class makes it easy to interact with API resources that
return a pageable list of entities (messages, contacts, etc.).
var cursor = project.queryMessages().limit(20);
cursor.each(function(err, message) {
if (err) throw err;
if (message)
{
console.log(message.content);
}
});
Example Usage
var telerivet = require('telerivet');
var API_KEY = 'YOUR_API_KEY'; // from https://telerivet.com/api/keys
var PROJECT_ID = 'YOUR_PROJECT_ID';
var tr = new telerivet.API(API_KEY);
var project = tr.initProjectById(PROJECT_ID);
// send message
project.sendMessage({
to_number: '555-0001',
content: 'Hello world!'
}, function(err, message) {
if (err) throw err;
console.log(message);
});
// import contact and add to group
project.getOrCreateContact({
name: 'John Smith',
phone_number: '555-0001',
vars: {
birthdate: '1981-03-04',
network: 'Vodacom'
}
}, function(err, contact) {
if (err) throw err;
project.getOrCreateGroup('Subscribers', function(err, group) {
if (err) throw err;
contact.addToGroup(group, function(err) {
if (err) throw err;
});
});
});
// query contact information
var namePrefix = 'John';
var cursor = project.queryContacts({
name: {prefix: namePrefix},
sort: 'name'
}).limit(20);
cursor.count(function(err, count) {
if (err) throw err;
console.log(count + " contacts matching " + namePrefix + ":");
cursor.each(function(err, contact) {
if (err) throw err;
if (contact != null)
{
console.log(contact.name + " " + contact.phone_number + " " + contact.vars.birthdate);
}
});
});