Track Delivery Status of Messages - Java
In this short tutorial, we'll show you how to track the delivery status of messages you send with Programmable Messaging in your Java web application. Twilio will notify you about the status of your SMS and MMS messages via a webhook, after which you can log this information or choose to send your delivery data back to Twilio.
Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks, or status callbacks. For more, check out our guide to Getting Started with Twilio Webhooks. Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.
The code snippets in this guide are written using Java and require Java JDK 8 or higher. They also make use of the Twilio Java SDK.
What is a Webhook?
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'll need to build a small web application that can accept HTTP requests.
Webhooks function the same for every Twilio application:
- Twilio makes an HTTP request to a URI that you provide.
- Your application performs whatever logic you feel necessary - read/write from a database, integrate with another API, or perform some computation.
- Your application then replies to Twilio with a TwiML response with the instructions you want Twilio to perform.
Receive Status Events in your Web Application
Statuses for which you can receive notifications include:
- accepted
- queued
- sending
- sent
- failed
- delivered
- undelivered
- receiving
- received
- read (WhatsApp only)
For a full description of these and other message statuses, see the API reference documentation.
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.
Let's take a look an example of how you can specify this parameter. Typically, you would include a URL that points to your application. Here we'll use a RequestBin URL instead, so that we can easily inspect the webhook requests that Twilio sends:
To get this code sample to run, do the following:
- Fill in your
ACCOUNT_SID
andAUTH_TOKEN
(found in the Twilio Console dashboard)
- Replace the
to
number (set first in thecreator
method) with your mobile number. - Replace the
from
phone number (set second in thecreator
method) with one of your Twilio numbers.
It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out How to Set Environment Variables for more information.
Next, head over to RequestBin, and create a new bin by clicking on the "public bin" link below the blue "Create Request Bin" button. Copy the new bin's URL, which is displayed near the top of the page. Replace the statusCallback
parameter value in the snippet with the URL of your bin.
When you run the code, you should receive your text message. In addition, you should see at least one request come into your RequestBin's request list, with content similar to:
"AccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
"From": "+15017250604"
"MessageSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"
"MessageStatus": "sent"
"SmsSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"
"SmsStatus": "sent"
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 status callback works, you're ready to handle the callback in your application.
Here's an example of how you might do this by logging the status for each message:
Get Status Events for TwiML Generated Messages
Replying to messages using TwiML? You can still track user actions via callback webhooks.
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>
What's next?
Now that you know how to track the delivery of messages based on carrier delivery status data, check out the resources below for additional information and related Twilio product documentation:
- Explore our guide How to Optimize Message Deliverability with Message Feedback.
- See how Message Feedback supports the Messaging Insights "One-time Password (OTP) Conversion Report". Learn how to analyze the effectiveness of messages sent to provide two-/multi-factor authentication (2FA, MFA) codes or other one-time passwords for user authentication or account verification.
- Shorten links in messages with your own company-branded domain and track click-through-rates with Link Shortening.
- Check out our tutorial How to set up a local Java development environment.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.