Bye bye Clickatell, hello bulksms. I need to send SMS from a ruby on rails app.
As I understand, some adult content spammers flooded Clickatell’s network, while using the shared short code with… well, adult content spam. US carriers started to block content from the short code essentially ruining it for everyone. I suppose the spammers couldn’t give a rat’s ass for the trouble they caused. There is a special place in hell for these people.
I needed another SMS gateway and stumbled upon usa.bulksms.com. Pricing was about the same as clickatell. Their API is adequate for my needs and I much prefer their backend account management abilities over clickatells.
Their HTTP EAPI returns most responses as pipe delimited values. You need to URL-encode all passed parameters, and of course POST, don’t GET. If possible, use port 5567, though they support 80 if needed.
The EAPI version is in the URL, e.g.: /eapi/submission/send_sms/2/2.0. This addresses backwards compatibility but also requires URL maintenance over time if you want to take advantage of future features.
Details of the above can be found here: http://usa.bulksms.com/docs/eapi/
Let’s send a message. For ease of demonstration, I’ll show this as a GET. Remember, POST only in production.
1 | /eapi/submission/send_sms/2/2.0?username=tim&password=abc123&message=Hi+world&msisdn=15551234567 |
Here we’ve used send_sms, passed in a username, password, message and msisdn. You can use a destination group in place of the msisdn. bullksms provides about 20 optional parameters. Here are a few interesting ones.
- test_always_succeed: for testing purposes – if set to 1, does basic validation (username, password, etc) of your submission, but stops short of actually submitting the messages, and returns a successful status code as if it had submitted them successfully.
- test_always_fail: as for test_always_succeed, but after basic validation, always returns a failure code.
- send_time: scheduled send time (see section on scheduling below), in format yyyy-mm-dd hh:mm:ss, relative to the time zone specified for your account. (also available using a unix time stamp)
- want_report: 0 or 1, default 1
- allow_concat_text_sms: enable sending of messages longer than 160 characters (unavailable in America)
Bulksms returns one of about 15 status codes. Important stuff here, you probably want to implement appropriate responding logic. Of interest to me is the batch_id returned on successful sends. This id will be used to later check status of the message.
Want to give it a spin? Sign up for an account and I they’ll give you a few credits for testing.
go get an account. I’ll be here when you come back…
Back? OK – Here’s all you need to test this. Fire up IRB, and paste these lines in, swapping out my username and password for yours. Notice I am using test_always_succeed so the message will not actually be forwarded on, and I won’t be charged.
1 2 3 4 5 6 7 | res = Net::HTTP.post_form(URI.parse('http://usa.bulksms.com:5567/eapi/submission/send_sms/2/2.0' ), {'username'=>'tim', 'password'=>'abc123', 'message'=>'TestMessage', 'msisdn'=>'15551234567', 'test_always_succeed'=>'1' }) puts res.body |
Cake walk…
Once I’ve sent a message I want to track status. Bulksms provides a get_report method. Using the batch_id received from send_sms. A GET example might look like this:
1 | /eapi/status_reports/get_report/2/2.0?username=tim&password=abc123&batch_id=10018 |
You may receive one of a few dozen status codes.
Finally we will track our remaining credits using get_credits. You can probably guess how this will look by now, but wait… One surprise. The get_credits is still at 1.1.1. Look at the difference in the URL.
1 | /eapi/status_reports/get_credits/1/1.1?username=tim&password=abc123 |
Now try it in the Ruby IRB.
1 2 3 4 5 6 | require 'net/http' require 'uri' res = Net::HTTP.post_form(URI.parse('http://usa.bulksms.com:5567/eapi/user/get_credits/1/1.1' ), {'username'=>'tim', 'password'=>'abc123'}) puts res.body |
Here’s what it looks like running in IRB on my Mac (of course I swapped out the username and password). Down towards the bottom you’ll see I had 172.04 credits when I ran this.
1 2 3 4 5 6 7 8 9 10 11 12 | tims-mac-pro:notify tim$ irb >> require 'net/http' > true >> require 'uri' => false >> res = Net::HTTP.post_form(URI.parse('http://usa.bulksms.com:5567/eapi/user/get_credits/1/1.1' ), ?> {'username'=>'tim', 'password'=>'abc123'}) => # >> puts res.body 0|172.04 => nil >> |
That should be enough to get you going. More SMS later. Maybe…
Tags: bulksms, clickatell, rails, ror, ruby, Ruby on Rails, SMS