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 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 requests 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:
- Receive and Reply to SMS and MMS Messages in C#
- Receive and Reply to SMS and MMS Messages in Java
- Receive and Reply to SMS and MMS Messages in Node.js
- Receive and Reply to SMS and MMS Messages in Python
- Receive and Reply to SMS and MMS Messages in Python with Amazon Lambda
- Receive and Reply to SMS and MMS Messages in Ruby
- Receive and Reply to SMS and MMS Messages on the ESP8266 with C++ and ngrok
- Receive and Reply to SMS and MMS Messages in PHP
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
MessageStatus: sent
To: +1512zzzyyyy
MessageSid: SM2xxxxxx
AccountSid: ACxxxxxxx
From: +1512xxxyyyy
ApiVersion: 2010-04-01Your 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.
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.
