...

In this lesson, we're going to explore how modules can be used to wrap an external API and make it available inside a pico. Along the way we'll explore using HTTP actions, creating our own actions, and managing API keys. 

For this lesson, we're going to be using the Twilio API to send SMS messages. Twilio provides a RESTful API for both voice and SMS interactions. Before you can complete this lesson, you'll need to register for a Twilio account. 

A 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")
    with body = {"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 POST 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 use 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 previous section is not as useful as it could be. If we put the send_sms() action in a ruleset and then use that ruleset as a module, 

## outline

1. Create a ruleset to serve as our module called twilio
2. write an action that makes an HTTP POST to send an SMS with credentials hard coded
3. write ruleset to test it
4. pull credentials into keys pragma. Still not great. 
5. Use module configuration to get keys out of module and into testing ruleset
6. use key module to get keys out of testing ruleset. 

...