Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

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 SMS, 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. Examples of message status 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?

        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.