Twilio's request to your incoming message Webhook URL

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:

Twilio also sends the following parameters when there are media, such as images, associated with the incoming message:

Twilio also attempts to look up geographic data based on the 'From' and 'To' phone numbers. Twilio sends the following parameters, if available:

For WhatsApp messages, Twilio sends additional parameters:

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

For incoming WhatsApp messages that originate from a "Click-to-WhatsApp" advertisement, Twilio includes the following parameters:

For messages that are replies to a specific message sent in the previous 7 days, Twilio will send these additional 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.

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, see this guide.