Writing Custom Code – User Guide

Custom actions make it possible to create many kinds of SMS services without needing programming expertise.

However, some kinds of SMS services can't be built by combining the basic actions provided by Telerivet. For example, if you want to integrate your SMS service with your own database or website, or connect to a third-party data source, then the basic actions and variables provided by Telerivet won't be enough.

In these cases, Telerivet provides two ways for you to run custom code to automatically handle incoming messages:

The Notify Webhook URL action lets you forward incoming messages to a script on your own server. This lets you write code in any programming language, such as PHP, Java, Python, or Ruby.
The Run JavaScript code action lets you write code in the JavaScript programming language. This code runs on Telerivet's servers whenever you receive an incoming message, so you don't need your own server.

Using a Webhook URL

Whenever a new message matches a Notify webhook URL action, Telerivet will automatically notify your server by making a HTTP POST request to a particular URL, where you can write your own code to handle the message and send replies.

Suppose you have a web server at http://myserver.example.com where you can run your own PHP scripts. (This example assumes that your code is written in PHP, though you can use any programming language.) Then you can create a Webhook rule pointing to a script on your server (e.g. telerivet.php):

The Webhook API documentation explains in detail how the incoming message will be passed to your script, and how your script can send automatic replies.

Writing JavaScript code

Whenever a new message matches a Run JavaScript code action, Telerivet will execute your JavaScript code on its own servers.

Telerivet provides several variables and functions to your JavaScript code that let you access properties of the incoming message, and perform actions equivalent to many rules, such as sending SMS messages or changing the contact's group membership.

In addition, Telerivet provides the capability for JavaScript code to make HTTP requests, which allows your service to interact with other web APIs. It also allows you to store limited amounts of data on Telerivet's servers.

For more information, see the complete Cloud Script API documentation.

Example 1

Suppose you want to create an SMS service that offers the weather forecast for any city in Tanzania, whenever someone sends your SMS service the name of a city.

Then you could sign up for the wunderground.com Weather API, and create a PHP script to that implements Telerivet's Webhook API like so:

<?php
    $webhook_secret = 'YOUR_WEBHOOK_SECRET_HERE';
    $country = 'Tanzania';
    $wug_key = 'YOUR_WUNDERGROUND_API_KEY_HERE';
    
    // Make sure request is actually generated by Telerivet
    if ($_POST['secret'] !== $webhook_secret)
    {
        header('HTTP/1.1 403 Forbidden');
        echo "Invalid webhook secret";
    }
    else if ($_POST['event'] == 'incoming_message')
    {
        $city = $_POST['content'];    
        
        // Make query to wunderground.com Weather API
        $city_query = $country."/".urlencode($city);    
        $url = "http://api.wunderground.com/api/{$wug_key}/forecast/q/{$city_query}.json";
        $json = file_get_contents($url);
        $res = json_decode($json, true);
        
        // Extract text forecast for tomorrow from Weather API response
        if (isset($res['forecast']))
        {
            $tomorrow = $res['forecast']['txt_forecast']['forecastday'][0];            
            $reply = $tomorrow['title'] . ": " . $tomorrow['fcttext_metric'];
        }
        else
        {
            $reply = "Unknown city '$city'.";
        }
        
        // Send reply via Telerivet Webhook API
        header("Content-Type: application/json");
        echo json_encode(array('messages' => 
            array(
                array('content' => $reply)
            )
        ));
    }

Then, if someone sends a text message like "Moshi", your service will respond with a message like this:

Friday: Overcast in the morning, then clear. High of 23C. Winds from the South at 5 to 15 km/h.

Example 2

Suppose you want to create the same weather forecast service as above, but without needing to run your own server.

In this case, you could create a service with a Run JavaScript code action as follows:

var wugKey = "YOUR_WUNDERGROUND_API_KEY_HERE";
var cityQuery = "Tanzania/" + encodeURIComponent(content);

var response = httpClient.request({
    url: "http://api.wunderground.com/api/" + 
        wugKey + "/forecast/q/" + cityQuery + ".json"
});

var res = JSON.parse(response.content);

if (res.forecast)
{
    var tomorrow = res.forecast.txt_forecast.forecastday[0];
    var forecast = tomorrow.fcttext_metric;
    sendReply(tomorrow.title + ": " + forecast);
}
else
{
    sendReply("Unknown city '"+message.content+"'.");
}