Twilio.com API Interface Plugin

Plugins & Plugin Development General Plugin Discussion
#1

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.

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

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)

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:

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.

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.

[sup](You can also see this quick and dirty explanation here: [url=http://new.digiflux.org/TwilioInterface.html]http://new.digiflux.org/TwilioInterface.html[/url]) [/sup]

#2

Neat. Always like to see other options for communications/messaging.

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

#3

Thanks.

I’ll make a change and update the files. I was following the Somfy plugin tutorial and forgot to change it.

#4

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

[sup]Update - 7 August 2013:[/sup]
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.

#5

I like it … What is the difference between:
InitiateVoiceCall
CustomVoiceCall

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

#6

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: [url=https://www.twilio.com/docs/api/twiml]https://www.twilio.com/docs/api/twiml[/url]

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.

[url=https://www.twilio.com/docs/api/rest/making-calls]https://www.twilio.com/docs/api/rest/making-calls[/url]

#7

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!

#8

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.

#9

Whoo hoo!

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

#10

[s]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 + ?[/s]

Got the voicecall working with the trial account.

#11

Suggestion to put the logo in the Plugin?

[url=http://status.twilio.com/images/logo.png]http://status.twilio.com/images/logo.png[/url]

#12

[quote=“Screamhouse, post:11, topic:175988”]Suggestion to put the logo in the Plugin?

[url=http://status.twilio.com/images/logo.png]http://status.twilio.com/images/logo.png[/url][/quote]

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.

#13

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

#14

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.)

#15

you can get as a European user, a US or Canada number as well for free.

#16

I just set this up with a UK-based Twilio number and it works really well. Good job, @SOlivas. 8)

#17
Sms sending might be disabled in the trial account, but you need to use a canadian or us number according to the service desk.
The trial account worked fined sending SMS from a UK number to a UK number. The US or Canadian number is apparently required when you want to send across international boundaries.
There is also a promocode available which gives you 20$ for free
This even works for a UK-based Twilio account! Thanks for the tip, @Screamhouse. :D
#18

The only unclear thingy is if we have lost our 30$ trial amount

#19

I’m having a difficult time getting the plugin to work. I put in my Account SID and Auth Token. I put in the caller ID number in xxx-xxx-xxxx format. I used the number that is listed in my Twilio account under verified caller IDs. Then, I created a new scene and in the LUUP section put in this code…

luup.call_action(“urn:twilioapi-org:serviceId:TwilioInterface1”, “InitiateVoiceCall”,{PhoneNumber= “773-xxx-2120”, Message=“Greetings from your Vera Home Automation System”}, 19)

I used 19 at the end because when I go to the Twilio Plugin and click advanced the id number is 19.

I run the scene but nothing happens. What am I doing wrong.

#20

[quote=“DyniaSanchez, post:19, topic:175988”]I’m having a difficult time getting the plugin to work. I put in my Account SID and Auth Token. I put in the caller ID number in xxx-xxx-xxxx format. I used the number that is listed in my Twilio account under verified caller IDs. Then, I created a new scene and in the LUUP section put in this code…

luup.call_action(“urn:twilioapi-org:serviceId:TwilioInterface1”, “InitiateVoiceCall”,{PhoneNumber= “773-xxx-2120”, Message=“Greetings from your Vera Home Automation System”}, 19)

I used 19 at the end because when I go to the Twilio Plugin and click advanced the id number is 19.

I run the scene but nothing happens. What am I doing wrong.[/quote]

I would double check your Account SID and key in the plugin variables, make sure you don’t have any extra spaces or other characters in it.

Also, try checking the logs, and see if you get an error.

And try running the code under the Apps->Develop Apps-Test Luup code (Lua) and see if it works.

Check the Logs section on your Twilio.com account, and see if it is showing anything as well.