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 SMS 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 phone number for sending and receiving SMS messages with your Telerivet account.

    Depending on your country, you can use different "gateways" for sending and receiving SMS, such as Nexmo, Twilio, 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 key to your account.

  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, which you can find on your API Keys page.

    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(array(
                    'messages' => array(
                        array('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 key to your account. 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 a contact 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 once for each contact. 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 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 this API method, see the documentation.

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.