Quick-Start Tutorials

The tutorials below are step-by-step guides to some of the most popular uses of Telerivet's Developer Platform. Just follow the steps and your mobile messaging service will be up and running in minutes.

First, you'll need to decide whether the code for your mobile messaging service will run on your own servers, or on Telerivet's servers.

Running Code on Your Own Servers

It's easy to integrate Telerivet with your own servers, for example to integrate SMS into your own web app, or to create a custom web interface for your users to interact with Telerivet.

When using your own servers, you'll integrate with Telerivet using the REST API and Webhook API.

Choose a tutorial below to get started:


Running Code on Telerivet's Servers

Telerivet makes it easy to build custom automated mobile messaging services without needing your own servers.

Using the Cloud Script API or Rules Engine, you can run your own code on Telerivet's servers to integrate Telerivet with third-party APIs, parse data from incoming messages, create automated conversation flows, and more.

Also, services can be created and edited directly from your web browser – so you don't need to install developer tools, and non-developers can easily maintain services too.

Choose a tutorial below to get started:



Send text messages from your server

This tutorial assumes you already have your own web server and have registered a Telerivet account.

  1. If you're using one of the following programming languages, download and install the Telerivet client library on your server:

  2. Next, add a route for sending and receiving text messages with your Telerivet account.

    Depending on your country, you can use different routes for sending and receiving SMS, such as Twilio, Vonage, or the Telerivet Gateway app (which works in any country but requires an Android phone).

    If you just want to experiment with the Telerivet API without sending real messages yet, you can add a Test Number.

  3. Next, add an API client to your project. The API client should have the "Send messages" permission. After adding the API client, generate an API key and copy the API key to your computer.

  4. Select your programming language to view sample code for sending an SMS message with the REST API.

    To run the example code, you'll need to fill in variables displayed in red like YOUR_API_KEY with the appropriate values for your account. Replace YOUR_API_KEY with the API key that you copied to your computer in the previous step. The other values like PROJECT_ID can be found at the bottom of the Developer API settings page in the Telerivet dashboard.

    The parameters content and to_number are required. For all available parameters, see the REST API documentation.

  5. If the code is working correctly, it should send a SMS message using the phone you've configured on Telerivet.

    If you're using a Test Number, the message will show up on your Messages page but will not actually be sent.

Receive incoming messages on your server

This tutorial assumes you already have your own web server and have registered a Telerivet account.

  1. Create a script on your server to handle incoming messages according to the Webhook API: 

    <?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';

    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else
    {
        if ($_POST['event'] == 'incoming_message')
        {
            $content = $_POST['content'];
            $from_number = $_POST['from_number'];
            $phone_id = $_POST['phone_id'];

            // do something with the message, e.g. send an autoreply
            header("Content-Type: application/json");
            echo json_encode([
                'messages' => [
                    ['content' => "Thanks for your message!"]
                ]
            ]);
        }
    }

    Replace YOUR_WEBHOOK_SECRET_HERE in the example code with a secret key of your choosing.

  2. If you haven't already done so, add a phone number for sending and receiving SMS messages with your Telerivet account.

  3. On your Services page, add a new service and select "Webhook API".

    Enter the URL of the script you just created, and the Webhook Secret from your script, then click "Done".

  4. Try sending a message to your Telerivet phone number. If your webhook is configured correctly, the sample code should send an auto-reply.

    You can also test your webhook without actually receiving an incoming SMS message. From the Services page, click "Test Service" and type a message to simulate.

    If your webhook doesn't work, see Debugging Webhooks for tips on how to fix it.

For more information on the Webhook API, see the full documentation.

Track message status on your server

This tutorial assumes that you have already configured your server to send SMS messages using Telerivet (see tutorial).

When you send a message via the Telerivet REST API, it is initially queued on Telerivet's servers. When Telerivet sends the message, the message status is updated to reflect whether the message was successfully sent or failed to send. Some gateway APIs also update the message status to reflect whether or not the message was actually delivered to the recipient's phone.

Telerivet's API makes it easy to receive updates whenever the message status changes or an error is encountered while sending messages.

  1. Create a script on your server to track message status according to the Webhook API:

    <?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';

    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else
    {
        if ($_POST['event'] == 'send_status')
        {
            $id = $_POST['id'];
            $status = $_POST['status'];
            $error_message = $_POST['error_message'];

            // do something with the message status, e.g. update your database
        }
    }

    Replace YOUR_WEBHOOK_SECRET_HERE in the example code with a secret key of your choosing.

    The status POST parameter will be one of the following strings: sent, queued, failed, failed_queued, delivered, not_delivered, or cancelled.

    For more details on the Webhook API and the meaning of each status code, see the full documentation.

  2. When you use Telerivet's REST API to send messages, set the status_url and status_secret parameters accordingly:

Import contacts from your server

If you already have contact information in your own database, the REST API lets you import contact information into Telerivet and keep it synchronized every time your database is updated. Once your contact information is stored in Telerivet, your staff can then use the Telerivet web app to send or schedule SMS campaigns.

First, add an API client to your project. The API client should have the "Edit contacts" permission. After adding the API client, generate an API key and copy the API key to your computer.

If you're using one of the following programming languages, download and install the Telerivet client library on your server:

Select your programming language to view sample code for importing contacts via the REST API:

When initially importing your contacts, you can write a script that loops over all the contacts in your database and calls the above REST API method in batches of up to 200 contacts. We recommend storing the returned contact ID in your own database, so you can later update the same contact record in Telerivet even if the contact's name or phone number changes.

The add_group_ids parameter is optional and will ensure that the contact is a member of a particular group in Telerivet (so you can easily send campaigns to all group members). After creating a group on your Contacts page, you can look up the group ID on the API Keys page.

The vars parameter for each contact is also optional, and lets you store custom data for each contact. (Learn more about storing custom data.)

Assuming that you have saved Telerivet's contact ID for each contact in your own database, you can later update it in Telerivet as shown below:

Alternative Method: If you are unable to store Telerivet's contact ID in your own database, you could store your own identifier for the contact in one of the custom variables (vars) in Telerivet. Then, you can update the contact like so:

For more details on the API method to import contacts, see the documentation.

Trigger an automated service

Telerivet enables building a wide range of automated services, such as polls and surveys, custom flows to engage with contacts, integrations with third-party services, and automations that update contacts and other data in your Telerivet account. The various types of automated services can be seen on the Add Service page in your Telerivet account.

Some automated services are triggered automatically when a particular event occurs in Telerivet, such as when an incoming message is received. However, some services are intended to be triggered manually – either via the Telerivet web app, the REST API, or the Cloud Script API. If you have already added an automated service, the Manually Triggered tab on the Services page shows the services that can be triggered via API.

Typically, automated services can be triggered for a particular phone number or contact in your Telerivet project. However, some automated services can be triggered for an existing message in your Telerivet project, and other automated services can apply to your Telerivet project in general. Telerivet uses the term "context" to refer to what the service is applied to – contact, message, or project.

  1. If you're using one of the following programming languages, download and install the Telerivet client library on your server:

  2. Next, add an API client to your project. The API client should have the "Send messages" permission. After adding the API client, generate an API key and copy the API key to your computer.

  3. The example code below shows the parameters that you will need to pass to the API in order to trigger a service, depending on the service's context.

    To run the example code, you'll need to fill in variables displayed in red like YOUR_API_KEY with the appropriate values. Replace YOUR_API_KEY with the API key that you copied to your computer in the previous step. The values for PROJECT_ID and SERVICE_ID can be found at the bottom of the Developer API settings page in the Telerivet dashboard.

    Trigger an automated service for a contact

    Most commonly, automated services are triggered for a contact (or a phone number), such as when sending a poll or custom flow to engage with a contact, or updating data for a particular contact.

    Select your programming language to view sample code for triggering a service.

    When triggering a service for a contact, the context parameter should be set to the string "contact". When providing a phone_number parameter, Telerivet will look up an existing contact with that phone number, or create a new one if it doesn't exist. (Alternatively, if your system already has an ID of a Telerivet contact, you can provide a contact_id parameter instead of phone_number.)

    For more details, see the service.invoke documentation.

    Trigger an automated service for a group of contacts

    It is also possible to trigger a service for an entire group of contacts in a single API request:

    For more details, see the project.sendBroadcast documentation.

    Schedule triggering an automated service for a contact at a future time

    Automated services can also be scheduled to be triggered at a future time or at a recurring interval.

    To trigger a service for multiple contacts at a future time, replace the to_number parameter with the group_id parameter.

    The project.scheduleMessage method provides several more parameters for scheduling messages at a particular time or at a recurring interval. For more details, see the project.scheduleMessage documentation.

    Trigger an automated service for a message

    Less commonly, if a service is triggered for an existing message in your Telerivet project, the context parameter should be set to the string "message" and the message_id parameter should be the ID of the message, as in the example below:

    Trigger an automated service for a project

    For services that are not triggered for a specific contact or message, the context parameter should be set to the string "project", as in the example below:

  4. After calling the service.invoke method, the REST API will return an object with various properties, including return_value, log_entries, errors, and sent_messages. The actual values returned in these properties will vary depending on the service. For more details, see the service.invoke documentation. (These properties are not provided when calling project.sendBroadcast or project.scheduleMessage.)

    If the API request fails, the API may return a HTTP error code and return an object with a message property describing the error (in which case the API client libraries will automatically throw an exception), or the API may return an object with an errors property set to an array of error messages encountered when processing the API request.

Send voice calls from your server

The REST API supports sending text-to-speech calls, recorded audio calls, and automated call flows.

This tutorial assumes that your project already has a route that supports sending voice calls.

  1. If you're using one of the following programming languages, download and install the Telerivet client library on your server:

  2. Next, add an API client to your project. The API client should have the "Send messages" permission. After adding the API client, generate an API key and copy the API key to your computer.

  3. To run the example code below, you'll need to fill in variables displayed in red like YOUR_API_KEY with the appropriate values for your account. Replace YOUR_API_KEY with the API key that you copied to your computer in the previous step. The other values like PROJECT_ID can be found at the bottom of the Developer API settings page in the Telerivet dashboard.

    Send automated call flow

    If you have configured an automated service that is triggered for outbound voice calls, you can send it using the service_id parameter:

    Send text-to-speech call

    To send a text-to-speech call, use the content, tts_lang, and tts_voice parameters:

    Send recorded audio call

    To send a recorded audio file, use the audio_url parameter with a publicly accessible URL of an MP3 file:

    For all available parameters, see the REST API documentation.

  4. If the code is working correctly, it should send a voice call using the route you've configured on Telerivet.

    If you're using a Test Number, the call will show up on your Messages page but will not actually be sent.

Create custom actions to handle incoming messages

Telerivet's Rules Engine makes it easy to create a wide variety of custom SMS services that automatically handle incoming messages and send replies.

By defining rules directly on Telerivet, you can create your own SMS service without needing programming expertise or needing to run your own servers.

Before starting this tutorial, register a Telerivet account if you haven't already done so, and add a phone number for sending and receiving SMS messages with your Telerivet account.

  1. From the Services page in your Telerivet project, add a new service and click "Custom Actions", or click the button below:

    Create New Service

  2. Click "Add condition".

  3. Update the condition according to the type of message you want to handle.

    For example, if you want to handle messages where the first word is "JOIN", your condition should look like this:

    if [[word1]] is join

  4. Click "Add action" at the end of the line extending diagonally from your condition. Actions added here will only be performed if the condition matches.

  5. Add the action you want to perform when the message matches the condition.

    For example, you could send an SMS reply, add or remove the contact from a group, send an email notification, or forward the SMS message to another phone number or group. See available actions

  6. Add all the conditions and actions you want to perform. You can click the "Test Service" button to simulate your service without sending a real message.

  7. When you're done adding actions, click "Done" to save your service. After you save the service, your actions will run automatically whenever you receive an incoming message.

Write JavaScript code to handle incoming messages

The Cloud Script API lets you use write custom code in JavaScript that runs on Telerivet's servers whenever you receive a new message.

For example, you can use Telerivet's Cloud Script API to build mobile messaging services that interact with third-party APIs, extract structured data from incoming messages, or implement a complex conversation flow.

Before starting this tutorial, register a Telerivet account if you haven't already done so, and add a phone number for sending and receiving SMS messages with your Telerivet account.

  1. From the Services page in your Telerivet project, add a new service and click "Cloud Script API", or click the button below:

    Create New Script

  2. Write the JavaScript code. (See the Cloud Script API reference for details and specific examples.) You can click the "Test Service" button to run your code without sending a real message.

  3. When your code is complete, click "Done" to save your service. After you save the service, your JavaScript code will run every time you receive an incoming message.