Page Comparison

...

1. Sign up for a developer account at Twilio

2. Study the Twilio API documentation for sending an SMS and making Twilio requests.

3. Generate an account_sid and the corresponding auth_token

4. Create a local file holding these keys. Do not check it in to any public repository.

5. Create a Twilio module to wrap their API:

   1. Write a function to return a page of messages sent

   2. Write a user-defined action to send an SMS

6. Write another ruleset to use and test your Twilio module by:

   1. calling the function and returning the messages

   2. defining a rule which actually sends an SMS

An SMS Action

Our first attempt will ignore some aspects of creating a useful module in order to just get something that works. Later we'll come back and clean those up. 

We'll start by defining an action called send_sms() that takes all of the information we need to use the Twilio API to send a message, including the Twilio API keys. 

A user-defined action is similar to a KRL function in that its body consists of a set of declarations, but instead of the last line being an expression representing the return value, the last line is an action. We used the defaction() keyword to define the function. In our case, the action will be the http:post() action that POSTs to the Twilio API. Here's our action definition:

send_sms = defaction(to, from, message, account_sid, auth_token){
  base_url = <<https://#{account_sid}:#{auth_token}@api.twilio.com/2010-04-01/Accounts/#{account_sid}/>>
  http:post(base_url + "Messages.json", form = 
                {"From":from,
                 "To":to,
                 "Body":message
                })
}

The action takes the following arguments:

• to - the number to send the SMS to

• from - the number the SMS is coming from (this must be a number from your Twilio account)

• message - the message to send

• account_sid - the Twilio account SID

• auth_token - the Twilio authentication token

The action creates a base URL using the instructions in the Twilio API docs and then POSTs to that URL. 

We can test this action, by creating a rule that uses it as follows. 

rule test_send_sms {
  select when test new_message
  send_sms(event:attr("to"),
           event:attr("from"),
           event:attr("message"),
           event:attr("account_sid"),
           event:attr("auth_token"))
}

This simple rule selects on the test:new_message event and uses the action we just defined. All the needed arguments must be included as event attributes. 

After we install a ruleset containing this action definition and rule in our pico, we can use the Sky Event Console to publish an event to the pico. If you're using valid values for the account SID, authentication token, and from phone number, the to phone number should receive an SMS with the message you give. 

The user-defined action hides some of the details of the Twilio API and presents a simple action that any rule can use to send an SMS. 

A Module for Twilio

The previously defined action is not as useful as it could be because it requires that the account SID and authorization token be passed in each time. This is where KRL's parameterized modules come in handy. 

Modules are parameterized using a configure pragma in the meta block. The variables declared in the configure pragma take on the values that are set when the module is used. The configuration allows for default values. 

The following is a complete module for the send_sms() action using configuration. 

ruleset io.picolabs.twilio_v2 {
  meta {
    configure using account_sid = ""
                    auth_token = ""
    provides 
        send_sms
  }

  global {
    send_sms = defaction(to, from, message) {
       base_url = <<https://#{account_sid}:#{auth_token}@api.twilio.com/2010-04-01/Accounts/#{account_sid}/>>
       http:post(base_url + "Messages.json", form = {
                "From":from,
                "To":to,
                "Body":message
            })
    }
  }
}

The configure pragma's defaults are the empty string since there's no workable default for the Twilio keys. You can see that those variables are referenced in the send_sms() action to create the based URL for the Twilio call. We avoid putting the keys in the module for two reasons:

1. Putting keys in the module is security risk since the file may be inadvertently shared or otherwise exposed.

2. The module should be general purpose, so that it can be used for more than one account. By not putting secrets in the module, we enable it to be used by multiple rulesets with their own keys.

We use a parameterized module by declaring its use in the meta block of the ruleset that wants to use the module. The use pragma allows parameters to be supplied for configuration variables. The following shows a ruleset that uses the Twilio module. 

ruleset io.picolabs.use_twilio_v2 {
  meta {
    use module io.picolabs.twilio_v2 alias twilio
        with account_sid = meta:rulesetConfig{"account_sid"}
             auth_token = meta:rulesetConfig{"auth_token"}
  }

  rule test_send_sms {
    select when test new_message
    twilio:send_sms(event:attr("to"),
                    event:attr("from"),
                    event:attr("message")
                   )
  }
}

This pattern uses meta:rulesetConfig() to get information from the configuration data when the ruleset is installed. It passes that information to the module in the use pragma so that the module has it.