Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

SMS Webhooks

When using Twilio's Programmable Messaging, there are two different types of webhooks or callbacks to consider.

For the first type, you configure a Twilio phone number to make a request to a webhook for responses to an incoming message. The second type is for receiving status updates on an individual message's delivery.

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.

Type 1: Incoming Message

Your Twilio phone numbers can use webhooks to receive inbound text messages.

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.

When a message comes in to Twilio for that phone number, Twilio will send either an HTTP POST (preferred), or an HTTP GET request to the URL you specify. When you get a request from Twilio, all of the information about that incoming message is sent in either the POST body or the GET query parameters.

For the complete list of parameters sent by Twilio, read more information about Twilio's request to your application.

Your application will need to return Twilio Markup Language (TwiML) as the response to Twilio's webhook request. This response will tell Twilio what to do - for instance, replying to the inbound text message with your own message that more information from the sender.

Ready to set up webhooks for your own application? The following tutorials walk you through configuring a webhook on a Twilio phone number. They also include sample code to generate TwiML responses for each of the following languages:

It is also possible to receive an incoming text message, and not send a reply message back to the user. To do that, simply send the following TwiML in your response to Twilio:

<Response></Response>

For more on this topic, read this support article: Receive SMS and MMS Messages without Responding

Type 2: Status Callbacks

When your application sends a text message through Twilio, you may want to determine if that message has been delivered successfully. There are two different ways of doing this: The first way is to ask Twilio for the delivery status of a particular message with the REST API, using its unique identifier (SID). The second way is to provide a StatusCallback URL when you send the message through the API.

Here is a code sample that shows how to set a webhook URL for status callbacks on outbound messages:

        
        
        
        

        Twilio will send an update to that URL every time the status changes; you'll find the status information in the MessageStatus value. (SmsStatus is provided for backwards compatibility.) Examples of MessageStatus values include accepted, sending, sent, failed, and delivered.

        Here is the complete list of message status values, which includes whether or not that status is for incoming messages, outgoing messages, or both.

        For more, read this support article: What are the Possible SMS and MMS Message Statuses, and What do They Mean?

        Your status delivery URL will receive an HTTP POST request with the application/x-www-form-urlencoded content type.

        The body of the status delivery message will look similar to the following:

        SmsSid: SM2xxxxxx
        SmsStatus: sent
        Body: McAvoy or Stewart? These timelines can get so confusing.
        MessageStatus: sent
        To: +1512zzzyyyy
        MessageSid: SM2xxxxxx
        AccountSid: ACxxxxxxx
        From: +1512xxxyyyy
        ApiVersion: 2010-04-01
        

        Your webhook will receive additional callbacks as the delivery status changes for a given message. This message status is sent, if the To phone number accepts the message, your webhook will get an almost identical message with a message status of delivered.

        We have a tutorial to help you set up message delivery tracking in each of these languages:

        We also have an in-depth guide about Best Practices for SMS Message Logging that goes into more depth about practical considerations when logging message delivery status, especially for large numbers of messages.

        Rate this page:

        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 browsing the Twilio tag on Stack Overflow.