README

PHP client library for Telerivet REST API

https://telerivet.com/api

Overview:
---------
This library makes it easy to integrate your web 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/php ,
as well as in the comments of the PHP source files. To learn what functionality is available, 
start with telerivet.php, lib/project.php, and lib/apicursor.php .

System Requirements:
--------------------
PHP 5.3 or higher
PHP json extension (usually enabled in PHP by default)
PHP curl extension (usually enabled in PHP by default)

Installation:
-------------
Copy this directory into your web application,
and require telerivet.php in your PHP code, e.g.:

require_once "path/to/telerivet.php";

Alternatively, if you use Composer for dependency management, 
you can add the following to your composer.json:

"require": {
    "telerivet/telerivet-php-client": "dev-master"
}

Example Usage:
--------------

require_once "path/to/telerivet.php";
   
$API_KEY = 'YOUR_API_KEY';           // from https://telerivet.com/api/keys
$PROJECT_ID = 'YOUR_PROJECT_ID';

$telerivet = new Telerivet_API($API_KEY);

$project = $telerivet->initProjectById($PROJECT_ID);

// Send a SMS message
$project->sendMessage(array(
    'to_number' => '555-0001',
    'content' => 'Hello world!'
));   

// Query contacts  
$name_prefix = 'John';
$cursor = $project->queryContacts(array(
    'name[prefix]' => $name_prefix,
    'sort' => 'name',
))->limit(20);

echo "{$cursor->count()} contacts matching $name_prefix:\n";

while ($cursor->hasNext())
{
    $contact = $cursor->next();
    echo "{$contact->name} {$contact->phone_number} {$contact->vars->birthdate}\n";        
}

// Import a contact
$contact = $project->getOrCreateContact(array(
    'name' => 'John Smith',
    'phone_number' => '555-0001',
    'vars' => array(
        'birthdate' => '1981-03-04',
        'network' => 'Vodacom'
    )
));

// Add a contact to a group    
$group = $project->getOrCreateGroup('Subscribers');
$contact->addToGroup($group);