Menu

Expand
Rate this page:

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)

https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media/MEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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.

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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Loading Code Sample...
        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        thanks-feedback-gif