Node.js client library for Telerivet REST API
JavaScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
LICENSE
README.md
package.json

README.md

Node.js client library for Telerivet REST API

http://telerivet.com/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);
        }
    });        
});