Twilio's StatusCallback mechanism sends an HTTP POST to a URL you specify every time a message transitions through a delivery status: queued, sending, sent, delivered, undelivered, or failed. Without StatusCallback configured, you must poll the Messages API to discover delivery outcomes, which is inefficient at scale and introduces latency between the delivery event and your application's awareness of it. With StatusCallback, your application receives delivery events in real time and can take immediate action on failures.
How to Configure StatusCallback
Add the StatusCallback parameter to your Twilio Messages API POST request body with the full HTTPS URL of your StatusCallback endpoint: the URL must be publicly accessible over HTTPS (Twilio requires TLS), must accept POST requests with an application/x-www-form-urlencoded body, and must return a 200 OK response within 10 seconds. To receive callbacks for all status transitions (not just the final one), also add the StatusCallbackMethod parameter with value POST, though POST is the default: GET is also supported but is not recommended for StatusCallback because delivery data should not be in a URL query string for logging reasons. For incoming messages and their replies, configure the StatusCallback URL on your Twilio phone number's Messaging Service or directly on the number under Console, then Phone Numbers, then Manage, then the specific number, setting the A Message Comes In StatusCallback URL field. Verify your StatusCallback endpoint is reachable before sending production messages by using the Twilio Console's Test Webhook tool under Messaging, then Services to send a test POST with sample parameters and confirm your server returns 200 and processes the body correctly.
The Complete List of Status Values
Queued means Twilio has accepted your message and placed it in an internal send queue: this is the initial status immediately after a successful API response. Sending means Twilio has begun transmitting the message to the carrier network: the message has left Twilio's queue and is in transit to the carrier's SMSC. Sent means the carrier has acknowledged receipt of the message from Twilio: the carrier now holds the message and will attempt delivery to the handset. Delivered means the carrier has confirmed successful delivery to the destination handset and returned a delivery receipt to Twilio: this is the final positive status and the only status that confirms the message reached the recipient. Undelivered means the carrier attempted delivery but could not reach the handset, and returned a failure delivery receipt to Twilio: the ErrorCode field in the callback will contain the specific failure reason code. Failed means the message could not be sent from Twilio at all (before reaching the carrier): this indicates a Twilio-level or account-level issue rather than a carrier delivery failure, and the ErrorCode will be in the 2xxxx or 3xxxx range.
How to Handle Each Status in Code
In your StatusCallback handler, extract the MessageSid, MessageStatus, ErrorCode, and ErrorMessage fields from the POST body using your server framework's form body parser, then update the corresponding message record in your database with the new status and error code: this gives you a real-time delivery audit trail without polling. For delivered status, mark the message record as confirmed delivered in your database and, if your application shows delivery indicators (read receipts, delivery ticks), update the UI state by pushing the status update through your real-time layer (WebSocket, Server-Sent Events, or a polling endpoint). For undelivered and failed statuses, trigger your application's error handling flow: look up the ErrorCode against your known-code map to determine whether to retry (transient errors), alert (compliance errors like 30007), or update the contact record (permanent errors like 30006 for landline numbers). Return 200 OK from your StatusCallback handler immediately after parsing the POST body, before performing any database writes or downstream processing: if your processing takes more than 10 seconds, Twilio will retry the callback, which can cause duplicate processing if your handler is not idempotent.
Building a Status Tracking System
Design your message database schema to include a status column (enum of queued, sending, sent, delivered, undelivered, failed), an error_code column (nullable integer), a status_updated_at timestamp, and a callback_received_at timestamp that records when each StatusCallback POST arrived: this enables delivery rate calculations and callback latency monitoring. Add idempotency to your StatusCallback handler by checking whether the incoming MessageSid and MessageStatus combination already exists in your database before processing: Twilio retries callback delivery if your endpoint returns a non-200 response, so duplicate callbacks are possible, and your handler must not double-count or double-alert on retried callbacks. Build a daily delivery report query that groups messages by final status and calculates delivery rate (delivered divided by total sent), undelivered rate (undelivered divided by total sent), and average time-to-delivered (status_updated_at minus created_at for delivered messages): these metrics are your baseline for detecting carrier or content issues. Alert when your delivery rate drops below 90 percent of the trailing 7-day average, as a sustained drop below this threshold almost always indicates a carrier compliance issue, a content filter trigger, or a registration problem that requires immediate investigation.
Conclusion
StatusCallback is the foundation of real-time delivery monitoring for Twilio messaging: configuring it correctly and building a proper handler turns individual delivery events into actionable data that drives your message quality monitoring and error response workflows. If you need help implementing a robust StatusCallback processing system, contact our team and we will design and build it within the hour.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.