Rate this page:

Our 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.

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

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:

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:

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:

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:

Latitude Latitude value of location being sent 51.51322977399644
Longitude Longitude value of location being sent -0.2197976373036567

Address of location being sent

187 Freston Road, London, Greater London W10 6TH

Label or name of location being sent
The Harrow Club

Status Callback Parameters

For status callbacks, Twilio also sends status-related parameters:

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

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 Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more