Sending an SMS with WebAPI is quite simple, especially since we added the {message:} object to the API. To get started we’ll need you to first create a WebAPI application in your Tropo account. Once you have set this up you will need to assign an SMS enabled phone number to the application, this part is required to send messages from the application. The next step is to make sure you have a messaging token associated with the application, since you will need this to start the session via our API (more on this in a few). Please note there are two Tokens associate with Tropo applications, one for voice calls, and one for messaging, we will want to use the Messaging token for our purposes here, but if you are interested in Voice calls please check out our guides for Scripting and WebAPI.

I will be using the Ruby WebAPI helper class for most of this example,  however I will post also include the raw JSON in-case you are using other libraries to render it (C#, Python, PHP, ect).

To start please take a look at the finished product, this is an example in Sinatra, using the Ruby helper class ( Tip: Additional WebAPI Power tips can be found in a previous blog posting here).

require 'rubygems'
require 'sinatra'
require 'tropo-webapi-ruby'

post '/' do
  sessions_object = Tropo::Generator.parse request.env['rack.input'].read
msg = sessions_object[:session][:parameters][:msg]
number_to_dial = sessions_object[:session][:parameters][:to]

tropo = Tropo::Generator.new do
            message({
                          :to => 'tel:+1'+number_to_dial,
                          :channel => 'TEXT',
                          :network => 'SMS'}) do
                             say     :value => "#{msg}"
                          end
            end

  tropo.response

end

If you have the WebAPI class installed then you can start Sinatra by just running sinatra my_app.rb from the command line.  This will start the server, and as long as you have the URL to this machine in the messaging portion of your application then we are all set!  If you are doing development, and are perhaps behind a firewall, you can get setup quickly by using something like tunnlr ( more info here ).

So lets review…  we have our server running, Tropo application created and pointed to our running server.  We have a messaging number associated with the application, and a messaging token.  I thin we are ready to rock and roll!!

So to send the message we need to send an HTTP request to Tropo’s sessions API.  So I’ll go ahead and use CURL, which is a command line tool which will among other things send HTTP requests.  If you dont have CURL you can just as easily place the URL in your browser, since this will accomplish the same end result ( Tip: make sure to substitute your number in the to parameter, and use your own messaging token in place of ‘my_messaging_token_id’ )

curl "http://api.tropo.com/1.0/sessions?action=create&token=my_messaging_token_id&msg=my+message+to+send&to=4075551212"

Now the magic begins! What will happen is this HTTP request will hit our API servers, and using the messaging tokenID we’ll route that to your applications startURL. This will in turn send a JSON payload to your messaging startURL similar to what you see below. Please pay close attention to the parameters located in this JSON body, this contains the message, the number we are sending a msg to, as well as various other parameters:

{
    "session": {
        "id": "76b05a0b25127dbf59a4627f6dcd38a7",
        "accountId": "12345",
        "timestamp": "2010-05-05T01:59:19.402Z",
        "userType": "NONE",
        "initialText": null,
        "callId":"092f931c4dddf0124ef426c56d26f98c",
        "parameters": {
            "token": "my_messaging_token_id",
            "action": "create",
	     "msg":"my message to send",
	     "to":"4075551212"
        }
    }
}

This JSON payload will hit out application and using the parse method of Tropo’s WebAPI helper class we can grab the associated values needed to send out message. This way we can use the same application to send multiple messages, to multiple recipients, with out having to change our code:

  sessions_object = Tropo::Generator.parse request.env['rack.input'].read
    msg = sessions_object[:session][:parameters][:msg]
    number_to_dial = sessions_object[:session][:parameters][:to]

Now we just use the generator method to build the return JSON payload, which we’ll send back to the Tropo session, which will then send the message. You can see the final JSON that our script sends back to Tropo below for your reference:

{
     "tropo":   [
         {
          "message": {
           "channel": "TEXT",
           "to": "tel:+14075551212",
            "say": [
                 {
                "value":"my message to send"
                 }
             ],
              "network": "SMS"
         }
    }
  ]
}

This payload instructs Tropo to send the message to your user, and all of this was started with a simple HTTP request, how cool is that! Now to wrap things up I wanted to touch on a few frequently asked questions we see related to messaging: When you send a message you can set the from callerID, however the number must be associated with the application sending the message. SMS Messages are carrier limited to 10 messages per number a minute, and currently the developer is responsible the throttling their messaging campaigns. Tropo does not block international SMS messages at this time, but delivery to international carriers is not officially supported at this time.

I really hope this information is helpful, and if there are any other questions please let us know, as our team is most certainly always standing by to offer any help our developers may require. You can always find us on Freenode irc.freenode.net in #tropo.

John Dyer

Tropo Support