= Twilio.com API Interface =

Original code posted: http://forum.micasaverde.com/index.php/topic,15499.msg117950.html#msg117950


== How to use ==

This plugin, what I called the Twilio.com API Plugin, will allow to you have your Vera call and say text, or send SMS messages using the Twilio.com Call and SMS APIs.  You will have to register for an account at www.twilio.com in order to use this plugin.

These are mandatory items that you need to configure before you can use the plugin:[[BR]]
[[BR]]
'''Account SID''' - Your Twilio.com account SID[[BR]]
'''Auth Token''' - Your Twilio.com account Authenrication Token[[BR]]
'''Caller ID''' - Phone number authorized to make calls[[BR]]
[[BR]]
These two items are optional (unless using the !CustomVoiceCall function):[[BR]]
[[BR]]
'''Custom MSG URL''' - URL that points to a custom TwiML creator[[BR]]
'''Custom MSG Var Name''' - Custom Message variable passed in URL[[BR]]


There are three functions that you can use:

'''!InitiateVoiceCall'''[[BR]]
'''SendSMSMessage'''[[BR]]
'''!CustomVoiceCall'''[[BR]]

The Twilio.com API's use what they have dubbed TwiML, which is an XML DTD that the API understands for passing it commands.


----


'''!InitiateVoiceCall''' will use the free twimlets.com/message TwiML generator to have Twilio's API speak the message you pass to the function.

''(Note:  we will assume our plugin has an ID of 66 in the following examples.  Make sure you replace the 66 in the code below with the actual ID number of the plugin on your system)''

Example:[[BR]]

{{{
luup.call_action("urn:twilioapi-org:serviceId:TwilioInterface1", "InitiateVoiceCall",{ !PhoneNumber= "555-555-1212", Message="Greetings from your Vera Home Automation System"}, 66)
}}}


'''!PhoneNumber''' = number of recipient

'''SendSMSMessage''' will send an SMS using Twilio's API:


Example:[[BR]]

{{{
luup.call_action("urn:twilioapi-org:serviceId:TwilioInterface1", "SendSMSMessage",{ PhoneNumber= "555-555-1212", Message="Greetings from your Vera Home Automation System"}, 66)
}}}


'''!PhoneNumber''' = number of recipient

'''!CustomVoiceCall''' will initiate a voice call, using the URL you specified in the Custom MSG URL by itself or with the Custom MSG Var Name config items.

Example:[[BR]]

{{{
luup.call_action("urn:twilioapi-org:serviceId:TwilioInterface1", "CustomVoiceCall",{ !PhoneNumber= "555-555-1212", Message="Hi there", !MsgFlag=2}, 66)
}}}


'''!PhoneNumber''' = number of recipient
'''!MsgFlag''' = 1 to only use custom URL, 2 to use custom URL and message variable name