Author Topic: Twilio.com API Interface Plugin  (Read 25679 times)

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Twilio.com API Interface Plugin
« on: July 03, 2013, 12:28:19 am »
Ok, here is my first try at making a plugin for the Vera 3.

** See reply below for updated files.

Note:  I've updated the plugin, so it will now have the Twilio icon.  See below for more info.

Files are now available on http://code.mios.com/trac/mios_twilio-api-iface

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:
Account SID - Your Twilio.com account SID
Auth Token - Your Twilio.com account Authenrication Token
Caller ID - Phone number authorized to make calls

These two items are optional (unless using the CustomVoiceCall function):
Custom MSG URL - URL that points to a custom TwiML creator
Custom MSG Var Name - Custom Message variable passed in URL


There are three functions that you can use:

InitiateVoiceCall
SendSMSMessage
CustomVoiceCall

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)

Code: [Select]
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:

Code: [Select]
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.

Code: [Select]
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


I added this to the apps.mios.com store yesterday, just waiting for approval.

Please let me know what you think.

(You can also see this quick and dirty explanation here: http://new.digiflux.org/TwilioInterface.html)
« Last Edit: August 09, 2013, 02:21:27 am by SOlivas »
Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline guessed

  • Master Member
  • *******
  • Posts: 5300
  • Karma: +92/-22
  • Release compat is not a bolted-on afterthought
Re: Twilio.com API Interface Plugin
« Reply #1 on: July 03, 2013, 02:07:47 am »
Neat.  Always like to see other options for communications/messaging.

You may want to switch from a "urn:upnp-org:..." to something more like "urn:twilio-com:..." to avoid name-spacing issues.  The UPnP spec lads are fussy about their NS being used for non-standardized stuff.

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #2 on: July 03, 2013, 02:29:52 am »
Thanks.

I'll make a change and update the files.  I was following the Somfy plugin tutorial and forgot to change it.
Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #3 on: July 03, 2013, 03:44:06 am »
Here are the updated files with the namespace changed in them.

Namespace is now twilioapi-org vice upnp-org


Edit: Added BSD license to top of implementation file.  New implementation file has been uploaded and new version published on apps portal -- will be available once it is approved

Update - 7 August 2013:
Edit 2:  I've finally figured out what should go into a .json file to display the standard tabs you see in a plugin's controls.  And, I also have added an icon for the plugin.  I've published the new version in the apps store with these updated files (version stays the same).  Once approved, you will have a version of the plugin with the Twilio icon.

I've added the new files here in the .zip file (so those who don't want to mess with moving the .png file manually can still see the default Vera icon by using the original files). 

Just unzip and replace the files on your Vera with these.  Then, you will need to login and place the TwilioLogo.png file under /www/cmh/skins/default/icons/ for it to show up correctly.

« Last Edit: August 07, 2013, 11:02:07 pm by SOlivas »
Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline RichardTSchaefer

  • Master Member
  • *******
  • Posts: 10091
  • Karma: +764/-142
Re: Twilio.com API Interface Plugin
« Reply #4 on: July 03, 2013, 08:14:11 am »
I like it ... What is the difference between:
   InitiateVoiceCall
   CustomVoiceCall

Looks like a pay as you go plan at penny a message ...

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #5 on: July 03, 2013, 10:13:13 am »
Yes, you have to pay for the services.  There is a test mode where you can call your own number for free.

The difference between the two functions is, InitiateVoiceCall will use the "TwiML" generator at http://www.twimlets.com to generate the necessary XML tags that the API needs to "say" your message.

The CustomVoiceCall function lets you get more advanced and substitute your own generator.  Instead of just a basic voice, you can also include tags to switch between genders, or ditch the standard message only feature and theoretically implement some of the more advanced features on the API, like conference calls, etc. (I haven't tried doing it, but I know that at the twimlets site, you can download their source code for the functions they present and modify them for your own purposes.)  (Actually, conference calls would likely need a new function implemented before they could be used.)

The documentation that shows how TwiML is generated is here:  https://www.twilio.com/docs/api/twiml

And here is the specifics on the "Call" function that is being used.  There are a few more options than just the basic "call and say" that you see here.

https://www.twilio.com/docs/api/rest/making-calls
« Last Edit: July 03, 2013, 10:23:50 am by olivas »
Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline S-F

  • Hero Member
  • *****
  • Posts: 1248
  • Karma: +62/-12
  • Clueless N00b
Re: Twilio.com API Interface Plugin
« Reply #6 on: July 03, 2013, 01:58:02 pm »
Wow. This is big. As I'm not a programer much of the discussion so far has eluded me. If I understand it correctly, this will allow Vera to send custom text messages and make phone calls and read TTS messages when answered for 2? per minute. I'm assuming that most if not all calls will be less than a minute so I can safely say 2? per call. This beats the pants off of the HomeSeer solution of having to buy a Way2Call for $300 +. I'm going to try this right now and report back.

EDIT. Could some good soul please give a little description on how to install this plugin? I've register a Twilio account and am eager to get started.

EDIT 2: The App Store has made me soft. I got it up and running and it's fantastic! The quality of the TTS does leave something to be desired though.

Vera is slowly but surely maturing with the hard work of the community developers. I'm becoming more and more pleased with it.

Thank you for this great plugin olivas!
« Last Edit: July 03, 2013, 03:37:11 pm by S-F »
My forum account was apparently hacked by a leprechaun. And he's drunk all of the time. If a post of mine seems a little off kilter, it's probably because he made it.

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #7 on: July 03, 2013, 06:42:19 pm »
Thanks!

If you go to twilio.com and check out the API, then use the scripts from twimlets.com, you can generate custom XML to change the voice characteristics.

There are more options, and when I get a chance, I will see what else from the API that might be useful.
Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #8 on: July 04, 2013, 06:44:59 pm »
Whoo hoo!

The plugin has been approved and is now available in the apps store for free!

Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline Crismaison

  • Sr. Member
  • ****
  • Posts: 451
  • Karma: +2/-0
Re: Twilio.com API Interface Plugin
« Reply #9 on: July 09, 2013, 01:37:38 pm »
do you need to buy an account before you can test this in vera? I have a trial account, but before spending 20 dollars, I would like to see if and how it works.
I did setup the plugin and an account, but it does not send a call or an sms to my mobile.

Second question is how to enter the phone numbers, does it include the 00 or do you use + ?


Got the voicecall working with the trial account.
« Last Edit: July 10, 2013, 01:36:03 pm by Screamhouse »
Vera lite - Everspring smoke & flood detectors - Fibaro doorsensors - 2 Foscams - Greenwave 6 node smartplug - Several Switches -Netatmo - PLEG - Twilio - DropBoxuploader - FindmyIphone user

Offline Crismaison

  • Sr. Member
  • ****
  • Posts: 451
  • Karma: +2/-0
Re: Twilio.com API Interface Plugin
« Reply #10 on: July 10, 2013, 03:52:39 pm »
Suggestion to put the logo in the Plugin?

http://status.twilio.com/images/logo.png
Vera lite - Everspring smoke & flood detectors - Fibaro doorsensors - 2 Foscams - Greenwave 6 node smartplug - Several Switches -Netatmo - PLEG - Twilio - DropBoxuploader - FindmyIphone user

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #11 on: July 13, 2013, 01:35:54 pm »
Suggestion to put the logo in the Plugin?

http://status.twilio.com/images/logo.png

Thanks.  I haven't played with the JSON files needed for logos yet.  I'll look at adding that in an update sometime in the future. 
Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline Crismaison

  • Sr. Member
  • ****
  • Posts: 451
  • Karma: +2/-0
Re: Twilio.com API Interface Plugin
« Reply #12 on: July 29, 2013, 02:30:52 pm »
Sms sending might be disabled in the trial account, but you need to use a canadian or us number according to the service desk.  There is also a promocode available which gives you 20$ for free
Vera lite - Everspring smoke & flood detectors - Fibaro doorsensors - 2 Foscams - Greenwave 6 node smartplug - Several Switches -Netatmo - PLEG - Twilio - DropBoxuploader - FindmyIphone user

Offline SOlivas

  • Sr. Member
  • ****
  • Posts: 282
  • Karma: +1/-1
Re: Twilio.com API Interface Plugin
« Reply #13 on: July 30, 2013, 01:52:29 am »
Sorry, it is easy to forget some of the restrictions on this.


If you need a US number, try anveo.com or teliax.com.

Anveo will allow you to get a US number, then forward SMS messages it receives to an international number.

Teliax works good for a DID number if you have an Asterisk system (US only, unless they have changed, it has been quite some time since I've setup my US number with them.  Until recently I had been living abroad for 11 years, but still needed a US number, so I've used them for years.  You can load money into the account, and when the funds get down to a certain limit, you can setup auto-reload.)



Vera 3 (1.5.622) / 9x GE/Jasco 45609 / 2x GE/Jasco 45612 / 2x GE/Jasco 45614 / 1x MIMO Lite
1x Twine (http://forum.micasaverde.com/index.php/topic,15617.0.html), DSC Security System, Honeywell  YTH8320ZW1007 Thermostat, 1x Fortrezz WWA-01, 1x CA9000 Wireless PIR Sensor

Offline Crismaison

  • Sr. Member
  • ****
  • Posts: 451
  • Karma: +2/-0
Re: Twilio.com API Interface Plugin
« Reply #14 on: July 30, 2013, 05:03:23 am »
you can get as a European user, a US or Canada number as well for free.
Vera lite - Everspring smoke & flood detectors - Fibaro doorsensors - 2 Foscams - Greenwave 6 node smartplug - Several Switches -Netatmo - PLEG - Twilio - DropBoxuploader - FindmyIphone user