Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Twilio's request to your incoming message 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(link takes you to an external page) 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.

(error)

Danger

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

parameters-in-twilios-request-to-your-application page anchor

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

request-parameters page anchor
PARAMETERDESCRIPTIONEXAMPLE
MessageSidA 34 character unique identifier for the message. May be used to later retrieve this message from the REST API.SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
SmsSidSame value as MessageSid. Deprecated and included for backward compatibility.SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
SmsMessageSidSame value as MessageSid. Deprecated and included for backward compatibility.SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AccountSidThe 34 character id of the Account this message is associated with.ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
MessagingServiceSidThe 34 character id of the Messaging Service associated with the message.MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
FromThe phone number or Channel address that sent this message.+14017122661
ToThe phone number or Channel address of the recipient.+15558675310
BodyThe text body of the message. Up to 1600 characters long.Ahoy! We can't wait to see what you build.
NumMediaThe number of media items associated with your message0
NumSegmentsThe number of message segments. (The value is always 1 for non-SMS/MMS messages.)1

WhatsApp-specific Parameters

whatsapp-specific-parameters page anchor

For WhatsApp messages, Twilio sends additional parameters:

PARAMETERDESCRIPTIONEXAMPLE
ProfileNameThe sender's WhatsApp profile namePerspective Coffee
WaIdThe sender's WhatsApp ID (typically a phone number)14017122661
Forwardedtrue if the message has been forwarded oncetrue
FrequentlyForwardedtrue if the message has been frequently forwarded(link takes you to an external page)true
ButtonTextThe text of a Quick reply buttonCancel Appointment

For incoming WhatsApp messages that share a location, Twilio includes the following parameters:

PARAMETERDESCRIPTIONEXAMPLE
LatitudeLatitude value of location being sent51.51322977399644
LongitudeLongitude value of location being sent-0.2197976373036567
AddressAddress of location being sent187 Freston Road, London, Greater London W10 6TH
LabelLabel or name of location being sentThe Harrow Club

For incoming WhatsApp messages that originate from a "Click-to-WhatsApp" advertisement(link takes you to an external page), Twilio includes the following parameters:

PARAMETERDESCRIPTIONEXAMPLE
ReferralBodyBody text of the advertisementLearn more about our company by sending us a message on WhatsApp
ReferralHeadlineHeadline text of the advertisementSend us a message
ReferralSourceIdMeta/WhatsApp's ID of the advertisement118588094077142
ReferralSourceTypeThe type of the advertisementpost
ReferralSourceUrlA URL referencing the content of the media shown in the advertisement when the user clicked to send a messagehttps://fb.me/xyz123
ReferralMediaIdMeta/WhatsApp's ID of the advertisement media shown when the users clicked to send a message; this will not match the Twilio Media SIDe420b130-f934-4acf-a5e6-f964f776bxyz
ReferralMediaContentTypeMedia ContentType of the advertisement media shown to the user when the user clicked to send a messageimage/jpeg
ReferralMediaUrlA URL referencing the media shown to the user in the advertisementhttps://api.twilio.com/2010-04-01 /Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX /Messages/MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX /Media/MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ReferralNumMediaThe number of media items associated with a "Click to WhatsApp" advertisement.0
ReferralCtwaClidThe ID associated with a click to a "Click to WhatsApp" advertisement for integrating WhatsApp business messaging events to Meta's Conversions APIARAkLkA8rmlFeiCktEJQ-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:

PARAMETERDESCRIPTIONEXAMPLE
OriginalRepliedMessageSenderThe Sender of the original message that this message is replying towhatsapp:+14017122661
OriginalRepliedMessageSidThe SID of the original message that this message is replying toSMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Google Business Message-specific parameters

google-business-message-specific-parameters page anchor

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(link takes you to an external page) .
    • 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:

    • 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(link takes you to an external page) and Begin the conversation(link takes you to an external page) .
    • 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(link takes you to an external page). Data is subject to change as Google adds/remove information. Any locale values use well-formed IETF BCP 47(link takes you to an external page) 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.


Rate this page: