In this guide, we'll show you how to track the delivery status of messages you send with Programmable SMS in your Ruby web application. Twilio can notify you about the status of your SMS and MMS messages via a webhook and you can notify Twilio about messages you have confirmed to be delivered.
The code snippets in this guide are written using Ruby language version 2.0.0 or higher, and make use of the following modules:
Webhooks are user-defined HTTP callbacks. They are usually triggered by some event, such as receiving an SMS message or an incoming phone call. When that event occurs, Twilio makes an HTTP request (usually a POST or a GET) to the URL configured for the webhook.
To handle a webhook, you only need to build a small web application that can accept the HTTP requests. Almost all server-side programming languages offer some framework for you to do this. Examples across languages include ASP.NET MVC for C#, Servlets and Spark for Java, Express for Node.js, Django and Flask for Python, and Rails and Sinatra for Ruby. PHP has its own web app framework built in, although frameworks like Laravel, Symfony and Yii are also popular.
Whichever framework and language you choose, webhooks function the same for every Twilio application. They will make an HTTP request to a URI that you provide to Twilio. Your application performs whatever logic you feel necessary - read/write from a database, integrate with another API or perform some computation - then replies to Twilio with a TwiML response with the instructions you want Twilio to perform.
Statuses for which you can receive notifications include: queued, failed, sent, delivered, and undelivered. For a full description of these and other message statuses, see the API reference.
To get Twilio to call your webhook, you need to provide a URL to your application in the StatusCallback parameter of each message for which you want the status callbacks. Below is an example of how you can specify this parameter. Normally, you would use a URL in your application, but let's use PostBin so we can debug what Twilio sends your webhook.
To get this code sample to run, first fill in your Account SID and Auth Token (found on the Twilio Console dashboard), replace the 'From' phone number with one of your Twilio numbers, and replace the 'To' number with your mobile number. Then, head over to PostBin and create a new bin. Replace the StatusCallback parameter in the snippet to the URL of your new bin.
When you run the code, you should receive your text message. In addition, you should see at least one request come into your PostBin similar to this:
This request shows the MessageStatus of sent. Assuming all was successful, you should see that followed up by another request with a status of delivered (it may take a few minutes to show up).
Once you get the hang of how the StatusCallback works, you're ready to handle the callback in your own application. Below is an example of how you might do this, logging the status for each message.
When you reply to an incoming message with the <Message> verb, you can also provide an action attribute to specify the URL for your callback webhook. The callback can be the same as those explored in the previous sections.
<?xml version="1.0" encoding="UTF-8"?> <Response> <Message action="http://postb.in/b/1234abcd">This message will be tracked!</Message> </Response>
The Twilio Message Feedback API enables you to programmatically report back to Twilio critical deliverability information. Actions that indicate a message was received can then be used by Twilio to identify network issues and improve deliverability of your messages. For example, a user action could be a person entering their two-factor authentication code or clicking a unique link in a message.
We already have many sources of data to optimize overall delivery deliverability. We use direct feedback from our carrier partners, deliverability data from some our larger customers as well as various other monitoring techniques. But nothing trumps the live collective data of our customers. For your messages, we trust what you tell us the most.
By looking at both aggregate data and data specific to your account, we have a better chance at improving the delivery of your messages.
Submitting Message Feedback to Twilio is a three step process:
- When you send a message, let Twilio know that you are expecting a trackable user action by including the new ProvideFeedback=true parameter in the initial HTTP POST.
- Save the Message SID from the POST response. You’ll need this later.
- When the user takes the expected action, such as entering a PIN code, let Twilio know the message was received by sending a POST request to the Message Feedback instance subresource with Outcome=confirmed parameter. If the user does not take an action, do not POST anything.
Let's look at some code. First, here's some code that sends a message with a unique URL, setting the ProvideFeedback parameter to true and also saving the Message SID for later recall.
Next, here's the code we might run when the user clicks the unique URL. Based on the unique URL, we know the Message SID and can report back to Twilio that the message was successfully delivered.
Examples of user actions include:
- A user receives a passcode via SMS and enters it into a web site or app
- A user enters a temporary password.
- A user replies to a message with a call or SMS.
- A user clicks on a unique link contained in the message.
Once a user takes an action, you know for certain that they received the message. This information is submitted to Twilio, and we take care of the rest.