I’ve wanted to play with the Twilio client for a while. They have this great quick start but it’s written in PHP. Now I don’t mind PHP, but I prefer Ruby. If I’m going to write anything using the client, it’s going to be in Ruby, so I don’t see the point in learning it on PHP.

So, here is the meat of the quickstart done up as a Rails 3.1 application.

First, generate the application.

$ rails new twilio
      create
      create  README
      create  Rakefile
      create  config.ru
      create  .gitignore
      create  Gemfile
      create  app
      ...

This creates a new Rails 3.1 app in the current directory called twilio. Change to this directory, and add a line to your Gemfile:

gem 'twilio-ruby'

Run bundle install to add the official Twilio gem to your bundle.

Next, head on over to your Twilio account and get your SID and auth token. Those can go in an initializer, config/initializers/twilio.rb:

TwilioAccountSID="AC........"
TwilioAuthToken="......."

Those are the magic tokens that let you authenticate yourself to the Twilio API, and more importantly for them, let them bill you.

Next, head on over to app/helpers/application_helper.rb:

module ApplicationHelper
  def twilio_javascript_include_tag
    javascript_include_tag "http://static.twilio.com/libs/twiliojs/1.0/twilio.min.js"
  end
end

Then in app/views/layouts/application.html.erb add that helper in the head:

  <%= stylesheet_link_tag    "application" %>
  <%= javascript_include_tag "application" %>
  <%= twilio_javascript_include_tag  %>
  <%= csrf_meta_tags %>

Yea, you could have put the code right in the layout, but I like sparse layout files.

Next up, create a controller:

$ rails generate controller client index
      create  app/controllers/client_controller.rb
       route  get "client/index"
      invoke  erb
      create    app/views/client
      create    app/views/client/index.html.erb
      invoke  test_unit
      create    test/functional/client_controller_test.rb
      invoke  helper
      create    app/helpers/client_helper.rb
      invoke    test_unit
      create      test/unit/helpers/client_helper_test.rb
      invoke  assets
      invoke    coffee
      create      app/assets/javascripts/client.js.coffee
      invoke    scss
      create      app/assets/stylesheets/client.css.scss

Then add root :to => ‘client#index’ to config/routes.rb so that your new view is displayed in the root url.

Run rails server or whatever you do to start your dev instance and browse to it. You should get the usual “find me in app/views/client/index.html.erb” message. Check the headers to make sure the library is being installed. The rest of the examples then deal with app/views/client/index.html.erb and app/helpers/client_helper.rb.

For the first example you want:

Helper:

module ClientHelper

  def twilio_token
    capability = Twilio::Util::Capability.new TwilioAccountSID, TwilioAuthToken
    capability.allow_client_outgoing "APabe7650f654fc34655fc81ae71caa3ff"
    capability.generate
  end
end

View:

<%= javascript_tag do %>
function call() {
  Twilio.Device.connect();
}

function hangup() {
  Twilio.Device.disconnectAll();
}

$(function() {
  Twilio.Device.setup("<%= twilio_token %>");

  Twilio.Device.ready(function (device) {
    $("#log").text("Ready");
  });

  Twilio.Device.error(function (error) {
    $("#log").text("Error: " + error.message);
  });

  Twilio.Device.connect(function (conn) {
    $("#log").text("Successfully established call");
  });
});
<% end %>
<button class="call" onclick="call();">
  Call
</button>

For the second example, you just change the view.

<%= javascript_tag do %>
function call() {
  Twilio.Device.connect();
}

function hangup() {
  Twilio.Device.disconnectAll();
}

$(function() {
  Twilio.Device.setup("<%= twilio_token %>");

  Twilio.Device.ready(function (device) {
    $("#log").text("Ready");
  });

  Twilio.Device.error(function (error) {
    $("#log").text("Error: " + error.message);
  });

  Twilio.Device.disconnect(function (conn) {
    $("#log").text("Call ended");
  });

  Twilio.Device.connect(function (conn) {
    $("#log").text("Successfully established call");
  });
});
<% end %>
<button class="call" onclick="call();">
  Call
</button>

<button class="hangup" onclick="hangup();">
  Hangup
</button>

<div id="log">Loading pigeons...</div>

For the third example we’ll have to change the helper and the view accordingly:

app/helpers/client_helper.rb (note I’m using my own sandbox id. You get your own inside the Twilio account page!)

module ClientHelper
  def twilio_token
    capability = Twilio::Util::Capability.new TwilioAccountSID, TwilioAuthToken
    capability.allow_client_outgoing "AP..."
    capability.allow_client_incoming 'jenny'
    capability.generate
  end
end

app/views/client/index.html.erb

%= javascript_tag do %>
function call() {
  Twilio.Device.connect();
}

function hangup() {
  Twilio.Device.disconnectAll();
}

$(function() {
  Twilio.Device.setup("<%= twilio_token %>");

  Twilio.Device.ready(function (device) {
    $("#log").text("Ready");
  });

  Twilio.Device.error(function (error) {
    $("#log").text("Error: " + error.message);
  });

  Twilio.Device.disconnect(function (conn) {
    $("#log").text("Call ended");
  });

  Twilio.Device.connect(function (conn) {
    $("#log").text("Successfully established call");
  });

  Twilio.Device.incoming(function (conn) {
    $("#log").text("Incoming connection from " + conn.parameters.From);
    // accept the incoming connection and start two-way audio
    conn.accept();
  });

});
<% end %>
<button class="call" onclick="call();">
  Call
</button>

<button class="hangup" onclick="hangup();">
  Hangup
</button>

<div id="log">Loading pigeons...</div>

Now, hook up a new action in the client controller to redirect the call from Twilio to the app inside app/controllers/client_controller.rb

def incoming
  response = Twilio::TwiML::Response.new do |r|
    r.Dial  do |d|
      d.Client 'jenny'
    end
  end

  render :text => response.text
end

Don’t forget to add post “client/incoming” to config/routes.rb. Then point your sandbox URL to your dev box, such as http://yourhome.com:3000/client/incoming.xml.

As a bonus, here’s a rake task to log in to a remote host and set up an ssh tunnel on remote port 3000 to local port 3000:

namespace :tunnel do
  desc "Start a ssh tunnel"
  task :start => :environment do

    public_host_username = "sean"
    public_host = "home.ertw.com"
    public_port = 3000

    local_port = 3000

    puts "Starting tunnel #{public_host}:#{public_port} \
          to 127.0.0.1:#{local_port}"

    exec "ssh -nNT -g -R *:#{public_port}:127.0.0.1:#{local_port} \
                           #{public_host_username}@#{public_host}"
  end
end

There are two more examples in the quickstart, but as they are more of the same, I’ll leave them for another post. I’d also like to try rewriting the Javascript in Coffeescript.

Update – Code is at https://github.com/swalberg/twilio-client-ruby

a

When I set it up a couple of years ago, I used SMS Gateway which was $10 for 100 SMSes. I was able to page with a simple curl command. However I’d get the odd page that wouldn’t go through, and despite being very responsive, the support wasn’t very reassuring.

Now that I’ve depleted my 100 pages, I figured I’d move over to Twilio because they’re pretty slick, and the reliability has to be better.

Some Nagios code, first:

define contactgroup{
        contactgroup_name       important
        alias                   Sean Buzz
        members                 sean, page
}
define contact{
        contact_name                    page
        alias                           page
        service_notification_commands   notify-by-page
        host_notification_commands      host-notify-by-page
        service_notification_period 24x7
        host_notification_period 24x7
        service_notification_options w,u,c,r
        host_notification_options d,u,r
        pager                           nobody@localhost
}
define service{
        use                             local-service         ; Name of service template to use
        host_name                       localhost
        service_description             smallpayroll.ca
        contact_groups                  important
        check_command                   check_http_string!smallpayroll.ca!Easy to use
        }

The first stanza creates a contact group called “important” that emails sean, and pages. The second stanza implements the “host-notify-by-page” and “notify-by-page” which do the actual paging. The final stanza is an example of a service that would get paged on. If the check_http_string check fails, the “important” contact group is notified.

The code to page is as follows:

define command {
        command_name    notify-by-page
        command_line    curl --data-urlencode "From=YOURTWILIONUMBER" --data-urlencode "To=YOURCELL" --data-urlencode "Body=[Nagios] $NOTIFICATIONTYPE$ $HOSTALIAS$/$SERVICEDESC$ is $SERVICESTATE$" https://SID:TOKEN@api.twilio.com/2010-04-01/Accounts/SID/SMS/Messages >> /tmp/sms
}
define command {
        command_name    host-notify-by-page
        command_line    curl --data-urlencode "From=YOURTWILIONUMBER" --data-urlencode "To=YOURCELL" --data-urlencode "Body=[Nagios] $HOSTSTATE$ alert for $HOSTNAME$" https://SID:TOKEN@api.twilio.com/2010-04-01/Accounts/SID/SMS/Messages >> /tmp/sms
}

To get the SID and TOKEN (note there are two instances of the SID, the second is in the URL right after accounts) go to your dashboard and look at the top:

To get a number click on Numbers then Buy a Number:

Then search for a number. It should be in the USA, as it looks like Canadian numbers don’t support SMS. You can verify this by clicking on “Buy”:

Buy the number for $1/month. You don’t have to set up any URLs with it if you’re doing outbound only.

YOURCELL should be obvious It could also be templated within Nagios.

a

The Erlang C model is used for this, it has the built in assumption that if agents are busy then the callers queue. This is much like a Mongrel or FastCGI “agent”, with requests coming in from a front end web server.

Using the Erlang C calculator here, I can figure out how many agents I need, given the desired service level.

• Arrivals: 600/minute (10 req/sec)
• Service time: 0.2s
• Service level: 99.9% within 0.3 s

Gives 5 agents or Mongrels. From there you can work backward with existing models to figure out how many computers you need.

With the calculator you can also fix the number of agents and figure out capacity, or blockage, or whatever.

This assumes that incoming requests follow the Poisson distribution, which I have no idea if it is true. Anyone?
Edit: Sorry, I managed to lose half the post and had to redo it.

a

How to configure SIP and NAT
Expose VoIP Problems Using Wireshark

a

How to configure SIP and NAT
Expose VoIP problems with Wireshark

Special thanks to Bill Reid, John Lange, and Les Bester of Les.net for letting me bounce ideas off of them, and again to Les for providing me some testing endpoints.

a

A local college radio station is being called to task for the following alleged infractions, committed over a year ago.

The examination also revealed shortfalls relating to the following three conditions of licence:

1. the licensee broadcast a level of 4.73% category 3 music instead of the weekly minimum of 5%;
2. the licensee broadcast a weekly level of 0.83% news instead of the weekly minimum of 4%; and
3. the absence of any formal educational programming despite its condition of licence to broadcast a minimum of two hours of such programming.

A hearing was called and people were flown in from all over the country to attend. All because a college radio station didn’t play some news and missed a few minutes of “category 3 music”.

I realize spectrum is a limited commodity, but gee-whiz, isn’t there a more efficient way of handling this?

a

It’s actually quite easy in theory, since you can Dial() any sort of address, but the trick is to integrate it with the dialplan.

A bit of research found this page which is good, but it assumes that everything gets forwarded to the SIP macro. Using part of his recipe:

exten => _[a-z].,1,Macro(uridial,${EXTEN}@${SIPDOMAIN})
exten => _[A-Z].,1,Macro(uridial,${EXTEN}@${SIPDOMAIN})

means that only those addresses that start with a letter will be dialed as SIP, which rules out numeric addresses (like 613@fwd.pulver.com for echo testing).

I like his idea, though, so I decided that I’d keep it, and prefix any numeric sip addresses with sip: so that the extension above would be caught. Then it was a matter of modifying his macro to look for sip: in front of a URI and strip it. The results are:

; Dials a SIP URI
[macro-uridial]

; First, assume it’s not a sip: type address
exten => s,1,Set(destination=${ARG1})
exten => s,n,NoOp(First 6 chars are ${ARG1:0:6})
; We see them as url encoded (ie : is really %3a)
; check to see if the first *six* chars match it then
exten => s,n,GotoIf($["${ARG1:0:6}" != "sip%3a"]?nowdial|1)
; we fell through because there was a sip: at the beginning, so
; strip the digits and then dial
exten => s,n,Set(destination=${ARG1:6})
exten => s,n,GoTo(nowdial,1)
; At this point it’s a proper uri
exten => nowdial,1,NoOp(Calling remote SIP peer ${destination})
exten => nowdial,n,Dial(SIP/${destination},120,tr)
exten => nowdial,n,Congestion()

In the end it turned out to be an exercise in learning how Asterisk works more than anything else, ie the %3a translation, the implicit breaking up of the address into $EXTEN and $SIPDOMAIN, and also the format of GotoIf.

a

ENUM is a method for mapping PSTN style phone numbers to a URI, such as SIP or a mailto, through the global DNS. My office phone, 204.975.5987, would then become 7.8.9.5.5.7.9.4.0.2.1.e164.arpa by reversing the digits, adding the top level country code of 1, and looking within the e164.arpa zone. Simplifying greatly, the response might either be nothing, meaning I can’t be reached by IP, or it might be something like sip:seanwalberg@ceridian.ca, meaning that I can be reached via SIP through that address.

One consumer of this information would be telecos. Rather than paying my carrier (MTS/Allstream) for terminating the call, they could use the sip URI to call me over the Internet and pocket the difference. The other would be regular people who are replacing their phones with either computers or smarter IP phones, and want to make the query themselves to avoid paying long distance.

Almost two years ago I wrote Either you’ve got a SIP address, or you’re not worth talking to to point out that the eventual goal will be phasing out of PSTN style numbers in favour of SIP URIs, which are basically email addresses.

Since telephones with their 12 buttons aren’t too good at entering SIP URIs such as “seanwalberg@ceridian.ca”, ENUM is one transition mechanism. But involve telecos and large committees, and you get delay and disagreements. Already there are two types of ENUM being proposed, one for carriers, one for the public. And since DNS is delegated differently than PSTN numbers, how does a regular person like me update my records securely (while making sure that an evil person can’t update my records?)

So this led me to think, “Why do we even need ENUM?”. Why not put a SIP address on your business card along with all the other numbers people put there? (Don’t quote me, but I remember Nortel did this) People who want to use SIP will use SIP. People who can’t won’t.

From the carrier perspective, if they’re so interested in saving money by offloading calls to the Internet, why not let them come up with their own transition mechanism? They’ve done this before for toll free and local number portability.

I suppose what I’m really saying is that the problem isn’t so much technical as it is marketing. How many people have some form of instant messaging client, or even several? What would it take people to move to a SIP based client? If people started using SIP based instant messaging, or even if it were supported under popular IM clients (didn’t MSN support it for a brief period), wouldn’t vendors have incentive to make hard phones capable of dialing SIP? (I pointed out last night that a small keypad was no impediment to the adoption of SMS messaging)

While I applaud the efforts of those involved with ENUM, I wonder if it wouldn’t be easier just to draw a line in the sand and not try and integrate the two networks. Instead, focus on promoting the SIP network, and let the benefits and features draw people in.

a

On another voice related note, John Lange has started up the Canadian Association of Voice over IP Providers, a sort of lobby/working group for Canadian ITSPs. The goal is to present an independent perspective on VoIP regulatory issues to the Canadian Radio and Telecommunications Committee (CRTC) and to work in cooperation with Local Exchange Carriers (LECs) to ensure interoperability between VoIP networks and the Public Switched Telephone Network (PSTN).

a

It’s an interesting thought, with many good arguments for and against.

On the surface, it may appear that BS is trying to have their cake and eat it too. People using their network pay for the access already, either by cash or reciprocal traffic arrangements. So, company X may connect to provider Y who in turn connects to BS. Y pays BS for the traffic it uses and X pays Y. BS may connect to another ISP who agrees to a reciprocal arrangement whereby each carrier will carry the other’s traffic free of charge.

In this scenario, the network is paid for, and any argument about “the Internet is getting faster and we can’t keep up” should be able to be taken care of by BS charging more to Y who passes it on to X should X be the person using the traffic.

On the other hand, one could look upon this as a value-add. “Yahoo!, pay me, and I’ll make sure your traffic has priority on my network”. (As an aside, giving traffic priority doesn’t always refer to a strict priority queue where Yahoo! always beats out Google and other traffic. It could be a guaranteed portion of the pipe) From this perspective, it seems reasonable to auction off different priorities within the BS network, assuming there is a market.

Of course, the “value” part of “value-add” is dubious. BS isn’t the whole Internet, and the hop-by-hop nature of the Internet means that your traffic will only experience the increased performance over the BS network. If your cable modem network is pinned, this won’t help you.

Now that I write it out, I’m starting to think the free market approach is better. One of several things will happen:

- People will pay. By this, I mean the ultimate end product is priced such that people buy it, and the content provider maintains a satisfactory profit
- People won’t pay. If I’m only willing to spend $1 on a music download, and I won’t spend $1.05 to have it download 10 seconds faster, then no one will choose the high quality option, and we’re back to the Internet we have today where all traffic is equal
- It won’t work for the reasons cited before. Other carriers could choose to alter their peering to avoid the BS network, or the benefit of the service could be so small that people won’t pay.

Either way, I don’t see a long term problem. The market should take care of it, whether or not it’s good for BS is the question.

All that said, the old adage often accredited to John Gilmore applies: “The Internet treats censorship as damage, and routes around it”. In this case, if BS tries to push it too far, or misuses the idea, the Internet will take care of itself.

(Also have a look over at the VoIP blog for another take)

a