Twilio's Request to Your Webhook URL
When an incoming message arrives at your Twilio phone number, Twilio sends a request to your web application via a webhook request. This request contains information about the incoming message, such as its sender and any attached media. Your application can store this data or use it for customizing a response, for example.
Twilio makes HTTP requests to your application, just like a regular web browser, in the format application/x-www-form-urlencoded. By including parameters and values in its requests, Twilio sends data to your application that you can act upon before responding.
You can configure the URLs and HTTP Methods Twilio uses to make its requests via your account portal in the Twilio Console or using the REST API.
Please note: that Twilio cannot cache POSTs. If you want Twilio to cache static TwiML pages, then configure Twilio to make requests to your application using GET.
The parameters included in StatusCallback events vary by channel and event type and are subject to change in the future. Twilio will occasionally add new parameters without advance notice. When integrating with webhooks, it is important that your implementation is able to accept and correctly run signature validation on an evolving set of parameters. We strongly recommend using the provided signature validation library from a Twilio SDK and not implementing your own signature validation.
Parameters in Twilio's Request to your Application
When Twilio receives a message at one of your Twilio numbers or a WhatsApp-enabled number, it makes a synchronous HTTP request to the message URL configured for that number or Messaging Service and expects to receive TwiML in response.
Twilio sends the following parameters with its request as POST parameters or URL query parameters, depending on which HTTP method you've configured:
Request parameters
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| MessageSid | A 34 character unique identifier for the message. May be used to later retrieve this message from the REST API. | SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| SmsSid | Same value as MessageSid. Deprecated and included for backward compatibility. | SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| AccountSid | The 34 character id of the Account this message is associated with. | ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| MessagingServiceSid | The 34 character id of the Messaging Service associated with the message. | MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| From | The phone number or Channel address that sent this message. | +14017122661 |
| To | The phone number or Channel address of the recipient. | +15558675310 |
| Body | The text body of the message. Up to 1600 characters long. | "Ahoy! We can't wait to see what your build." |
| NumMedia | The number of media items associated with your message | 0 |
Media-related Parameters
Twilio also sends the following parameters when there are media, such as images, associated with the incoming message:
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| MediaContentType{N} | The ContentTypes for the Media stored at MediaUrl{N}. The order of MediaContentType{N} matches the order of MediaUrl{N}. If more than one media element is indicated by NumMedia than MediaContentType{N} will be used, where N is the zero-based index of the Media (e.g. MediaContentType0) |
image/jpeg |
| MediaUrl{N} | A URL referencing the content of the media received in the Message. If more than one media element is indicated by NumMedia than MediaUrl{N} will be used, where N is the zero-based index of the Media (e.g. MediaUrl0) |
|
Geographic Data-related Parameters
Twilio also attempts to look up geographic data based on the 'From' and 'To' phone numbers. Twilio sends the following parameters, if available:
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| FromCity | The city of the sender | SAN FRANCISCO |
| FromState | The state or province of the sender. | CA |
| FromZip | The postal code of the called sender. | 94103 |
| FromCountry | The country of the called sender. | US |
| ToCity | The city of the recipient. | SAUSALITO |
| ToState | The state or province of the recipient. | CA |
| ToZip | The postal code of the recipient. | 94965 |
| ToCountry | The country of the recipient. | US |
WhatsApp-specific Parameters
For WhatsApp messages, Twilio sends additional parameters:
| PARAMETER | DESCRIPTION | EXAMPLE |
| ProfileName | The sender's WhatsApp profile name | Perspective Coffee |
| WaId | The sender's WhatsApp ID (typically a phone number) | 14017122661 |
| Forwarded | true if the message has been forwarded once |
true |
| FrequentlyForwarded | true if the message has been frequently forwarded |
true |
| ButtonText | The text of a Quick reply button | Cancel Appointment |
For incoming WhatsApp messages that share a location, Twilio includes the following parameters:
| PARAMETER | DESCRIPTION | EXAMPLE |
| Latitude | Latitude value of location being sent | 51.51322977399644 |
| Longitude | Longitude value of location being sent | -0.2197976373036567 |
| Address |
Address of location being sent |
187 Freston Road, London, Greater London W10 6TH |
| Label |
Label or name of location being sent |
The Harrow Club |
For incoming WhatsApp messages that originate from a "Click-to-WhatsApp" advertisement, Twilio includes the following parameters:
| PARAMETER | DESCRIPTION | EXAMPLE |
| ReferralBody | Body text of the advertisement | Learn more about our company by sending us a message on WhatsApp |
| ReferralHeadline | Headline text of the advertisement | Send us a message |
| ReferralSourceId | Meta/WhatsApp's ID of the advertisement | 118588094077142 |
| ReferralSourceType | The type of the advertisement | post |
| ReferralSourceUrl | A URL referencing the content of the media shown in the advertisement when the user clicked to send a message | https://fb.me/xyz123 |
| ReferralMediaId | Meta/WhatsApp's ID of the advertisement media shown when the users clicked to send a message; this will not match the Twilio Media SID | e420b130-f934-4acf-a5e6-f964f776bxyz |
| ReferralMediaContentType | Media ContentType of the advertisement media shown to the user when the user clicked to send a message | image/jpeg |
| ReferralMediaUrl | A URL referencing the media shown to the user in the advertisement | https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media/MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| ReferralNumMedia | The number of media items associated with a "Click to WhatsApp" advertisement. | 0 |
For messages that are replies to a specific message sent in the previous 7 days, Twilio will send these additional parameters:
| OriginalRepliedMessageSender | The Sender of the original message that this message is replying to | whatsapp:+14017122661 |
| OriginalRepliedMessageSid | The SID of the original message that this message is replying to | SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
Google Business Message-specific parameters
For GBM messages, Google sends additional parameters with each message so you can better engage with your customer. Twilio passes this info through a single additional parameter, "ChannelMetadata", containing a JSON string with values:
- type: The type will be "gbm" for GBM-specific values
- data: The following data is contained:
- entryPoint: The messaging surface the user began the conversation from, as defined by EntryPoint.
- userInfo
- displayName: The profile name of the user who sent the message. If the user opts out of identity sharing, this field is empty.
- userDeviceLocale: The user's locale, reported by their device.
- widget:
- url: The URL of the website where the conversational surface launched.
- widgetContext: The data-bm-widget-context attribute value of the widget used to start the conversation.
- resolvedLocale: The best computed match of the user's locale (reported in userDeviceLocale) and the agent's supported locales (determined by specified conversational settings). See Localization and Begin the conversation.
- customContext: Custom metadata specified in the original outbound API request payload. For example, you can set a customContext on a quick reply button, and you will receive this customContext back when the end user taps that button.
- placeId: A unique identifier from the Google Places database for the location that the user messaged. Only appears in messages from location-specific entry points.
- nearPlaceId: A unique identifier from the Google Places database for the first location in a Local Pack. Confirm the locations that users want to chat with when you receive nearPlaceId values.
Twilio passes all non-empty Context values from Google. Data is subject to change as Google adds/remove information. Any locale values use well-formed IETF BCP 47 language tags.
Status Callback Parameters
For status callbacks, Twilio also sends status-related parameters:
| PARAMETER | DESCRIPTION | EXAMPLE |
|---|---|---|
| MessageStatus | The status of the message. Can be: accepted, queued, sending, sent, failed, delivered, undelivered, receiving, received, or read (WhatsApp only). For more information, see detailed descriptions. |
delivered |
| SmsStatus | Same as MessageStatus value. Deprecated and included for backward compatibility. | delivered |
| RawDlrDoneDate | Available on most SMS/MMS Delivered or Undelivered events only. This parameter is a passthrough of the Done Date included on the DLR (Delivery Receipt) that we receive from our carrier partners. It takes the format of YYMMDDhhmm where: YY = last two digits of the year (00-99), MM = month (01-12), DD = day (01-31), hh = hour (00-23), mm = minute (00-59). Additional details. | 2302172359 |
ErrorCode callback on unsuccessful WhatsApp messages
If message delivery with WhatsApp fails, the SmsStatus and MessageStatus parameters will read undelivered and Twilio will return Error 63016 as ErrorCode=63016 in the webhook response.
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.
