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.
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:
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 |
SmsMessageSid | 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 you build. |
NumMedia | The number of media items associated with your message | 0 |
NumSegments | The number of message segments. (The value is always 1 for non-SMS/MMS messages.) | 1 |
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 |
ReferralCtwaClid | The ID associated with a click to a "Click to WhatsApp" advertisement for integrating WhatsApp business messaging events to Meta's Conversions API | ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a |
For messages that are replies to a specific message sent in the previous 7 days, Twilio will send these additional parameters:
PARAMETER | DESCRIPTION | EXAMPLE |
---|---|---|
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 Messages (GBM) will be turned off on July 31, 2024. The Twilio GBM API and Google Business Profiles chat will no longer work after that point.
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:
data: The following data is contained:
userInfo
widget:
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.
In the context of Twilio documentation, status callbacks (and the webhooks configured for these) generally refer to events raised by the lifecycle of outgoing messages, rather than incoming messages as discussed on this page. Although incoming messages can theoretically also raise status callback events, the statues involved here can only be receiving
(a very transitory state) or received
; if an incoming message has failed to be received by Twilio or has not yet been received, then by definition Twilio cannot raise an event for such a message. Thus, incoming-message status callbacks have very little practical application. On the other hand, outgoing messages will change their status repeatedly throughout an entire lifecycle, and these status changes can be tracked by means of status callbacks and webhooks configured to receive them. For more information on outgoing-message status callbacks and webhooks, please see this guide.