(Classic) twilio

Anyone can create an account and provision phone numbers using the Twilio service. When someone calls or sends a text message to one of these numbers, Twilio uses a Web hook to call a RESTful Web service that the account owner has set up.  The response from the service should be an XML file that tells Twilio what to do.  The Twilio docs can be found here.

Events From Voice

Once you've signed up for a Twilio account, you can provision phone numbers and associate them with callback URLs, or Web hooks.  When one of your phone numbers is called, the Twillio service will POST to the Web hook associated with that number.  You can create and ESL to serve as the Webhook for the pico that is running responding to Twilio. 

The Twilio Module

A Twilio Module has been built. This module makes working with Twilio simple. 

The Twilio Library

One of the built-in libraries in Kynetx supports Twilio directly.  This makes sending Twilio directives easier.  As mentioned, you can control Twilio by sending back XML files the instruct the Twilio engine on what to do next.  The Twilio XML format is called TwilML.

The KRL Twilio library defines actions that send back TwilML. For example, if a rule set returned the following TwilML, the Twilio engine would respond by saying "Hello Monkey" to the caller:

<Response>
	<Say>Hello Monkey</Say>
</Response>

The following action in KRL does the same thing:

twilio:say("Hello Monkey")
	with voice = "woman"

The following table shows the actions associated with various TwilML directives.  The twilio:raw() action has no corresponding Twilio verb.  You can use it to send any XML you like to Twilio in case the preceding actions don't provide what you need.

The following is an example ruleset using the Kynetx Twilio Module:

ruleset a1299x191 {
  meta {
    name "Hello Monkey Demo"
    description <<
        Example Ruleset for twilio directives
    >>
    key twilio{
        "account_sid" : "your_account_sid",
        "auth_token"  : "your_auth_token"
    }
    use module a8x115 alias twilio with twiliokeys = keys:twilio()
    logging off
  }
  
  // create a rule that is fired on an inbound call
  rule answer {
    select when twilio inbound_call   
    pre{
        // find out who is calling
        callerid = event:attr("from");
        // set up a directory
        dir = {
                "+911": "The Man",
                "+8015552311": "Big Bird",
                "+8029875634": "Scam Artist"
            };
        dir_match = dir.pick("$.#{callerid}");
	name = dir_match.length() != 0 => dir_match | "Monkey";
    }
    {
        // Give Formal Greeting
        twilio:say("Hello #{name}");
        twilio:hangup();
    }
  }

You can expand the above example to ask the caller for his or her favorite number.  You gether input from the caller using the dial pad by adding the twilio:gather() action to the answer rule and add another rule to process the caller's response.  An example is given below:

ruleset a1299x191 {
  meta {
    name "Hello Monkey Demo"
    description <<
        Example Ruleset for twilio directives
    >>
    key twilio{
        "account_sid" : "your_account_sid",
        "auth_token"  : "your_auth_token"
    }
    use module a8x115 alias twilio with twiliokeys = keys:twilio()
    
    logging off
  }
  
  // create a rule that is fired on an inbound call
  rule answer {
    select when twilio inbound_call   
    pre{
        // find out who is calling
        callerid = event:attr("from");
        // set up a directory
        dir = {
                "+911": "The Man",
                "+8015552311": "Big Bird",
                "+8029875634": "Scam Artist"
            };
        dir_match = dir.pick("$.#{callerid}");
        name = dir_match.length() != 0 => dir_match | "Monkey";
    }
    {
        // Give Formal Greeting
        twilio:say("Hello #{name}");
        twilio:gather_start("monkey_handle")
            with numDigits="1";
          twilio:say("What is your favorite number?");
         twilio:gather_stop;
    }
  }
  
  rule picked {
    select when twilio monkey_handle
    pre {
        favorite = event:attr("Digits");
    }
    {
        twilio:say("Your favorite number is #{favorite}.");
        twilio:hangup();
    }
  } 
}

Any response from a gather action will have an event attribute called Digits that contains user input. The rule simply says it back to the caller, but you could store it in an entity variable for later use and, for example display it on a Web page for the monkey to see.

Call Event Parameters

Sending SMS

You can use the send_sms() action to send an SMS message using Twilio. The action takes three parameters:

1. The phone number to send the SMS to.
2. The phone number the SMS is from (should match the number in your Twilio account)
3. The message. 

The following ruleset shows a simple example of using Twilio to send an SMS when the notification:status event is raised. 

ruleset twilio_sms {
  meta {
        
        key twilio {"account_sid" : "<account SID here>",
                    "auth_token"  : "<auth token here>"
        }
        
        use module a8x115 alias twilio with twiliokeys = keys:twilio()
       
  } 
    rule sms {
      select when notification status 
      twilio:send_sms(event:attr("phone_number"), event:attr("from_number"), event:attr("message"));
    }
  
}

The ruleset loads the Twilio module using the keys you create in your Twilio account. 

Receiving SMS Events

Using Twilio to add SMS message capabilities to your rule set is simple.  Every Twilio number has an associated Web hook for voice calls and one for SMS messages.  If you've configured Twilio with an SMS webhook that is an ESL, rulesets installed in that pico will receive events from Twilio when your account receives an SMS. 

The table below gives the event parameters sent to your application when an SMS message is received.  They can accessed through the event:param() variable.