Twilio Parse Webhook SMS

Audience: Low-code Engineers

Skill Prerequisites: APIs, Actions, Tokens

Reads an incoming SMS that Twilio sends to your API endpoint, and puts its details in tokens: who sent it, which of your numbers received it, the text, and any picture links.

The action reads the current HTTP request only, so use it in the actions of an API endpoint that you've set as the webhook of a Twilio phone number.

note

This action is part of the Twilio SMS add-on, which is installed and licensed separately (feature package TWILIOSMS). If it isn't licensed, the action fails with a not-licensed error.

Typical Use Cases

• Let people text a keyword, such as STATUS 1234, and reply with information from your database
• Save incoming SMS as support tickets or messages
• Handle STOP or YES replies to messages you sent with Send SMS using Twilio

Don't use it to

• Read a Twilio status callback. Status callbacks have other fields, such as MessageStatus, which this action doesn't read.
• Send an SMS. Use Send SMS using Twilio.
• Read requests from other SMS providers. It only reads Twilio's field names.

Related Actions

Action Name	Description
Twilio Send Response to SMS Webhook	Replies to the incoming SMS and ends the webhook call.
Send SMS using Twilio	Sends a new SMS, for example to someone other than the sender.
Raw Response	Returns a custom response, for example a hand-written TwiML document.
Run SQL Query	Saves the incoming message or looks up data for the reply.

How receiving SMS works

1. Create an API endpoint on the APIs page. Set the HTTP method to POST, which is what Twilio uses by default. GET works too. Set Cross Domain Policy to Public, because Twilio's requests don't come from a web page on your domain. See Securing the webhook for the Access setting.
2. Add the actions. Start with Twilio Parse Webhook SMS, then the actions that handle the message, and end with Twilio Send Response to SMS Webhook.
3. Point Twilio at the endpoint. In the Twilio Console, open your phone number and, under Messaging, set A message comes in to Webhook with the endpoint's URL and the same HTTP method.
4. When an SMS arrives, Twilio calls the endpoint with the message details as form fields (or query string fields for GET). This action copies them into tokens.
5. The response tells Twilio what to do next, in Twilio's XML format, called TwiML. Send Response returns TwiML that replies with a message, or with nothing. If the endpoint doesn't return valid TwiML, Twilio logs an error in its Debugger.

Input Parameter Reference

The parameters unique to this action are listed below. Review the common parameters for all actions here.

This action has no input parameters. It always reads the current request.

Output Parameters Reference

Parameter	Description
Output Token	The prefix of the tokens the action creates, for example Sms for [Sms:From]. If it's empty, the prefix is Twilio.

The action creates these tokens. Fields that aren't in the request are set to an empty string.

Token	Description
[<Output Token>:MessageSid]	Twilio's 34-character ID of the incoming message.
[<Output Token>:AccountSid]	The ID of the Twilio account the message was sent to.
[<Output Token>:MessagingServiceSid]	The ID of the Twilio Messaging Service, if the number belongs to one.
[<Output Token>:From]	The number that sent the message, in E.164 format, for example +15555550123.
[<Output Token>:To]	Your Twilio number that received the message.
[<Output Token>:Body]	The text of the message, up to 1,600 characters.
[<Output Token>:NumMedia]	The number of pictures or other media in the message. 0 if there are none.
[<Output Token>:MediaUrl0], [<Output Token>:MediaUrl1], ...	The URL of each media item, starting at 0. They're only created when NumMedia is more than 0.
[<Output Token>:MediaContentType0], ...	The content type of each media item, for example image/jpeg.
[<Output Token>:FromCity], [<Output Token>:FromState], [<Output Token>:FromCountry]	Where the sender's number is registered, if Twilio knows.
[<Output Token>:FromZip]	Always empty in 1.28. See Considerations.
[<Output Token>:ToCity], [<Output Token>:ToState], [<Output Token>:ToZip], [<Output Token>:ToCountry]	Where your receiving number is registered, if Twilio knows.

Location fields aren't available in every country.

Securing the webhook

The action doesn't check the X-Twilio-Signature header that Twilio adds to its requests. It trusts whatever is posted to the endpoint. If the endpoint's Access is Public access, anyone who knows the URL can post a fake SMS, with any From number and text, and your actions run as if it came from Twilio.

To reduce the risk:

• Set Access to Restricted to API Keys, create an API key, and add it to the webhook URL in the Twilio Console, for example https://www.example.com/incoming-sms?apikey=<your API key>. Twilio then sends the key with every request. The key is part of the URL, so it can appear in logs. Treat it as a secret and change it if it leaks.
• Check [Sms:AccountSid] against your own Account SID in a condition. This only stops careless fakes, because the Account SID isn't secret.
• Don't trust [Sms:From] as proof of identity for anything sensitive, such as resetting a password or approving a payment.
• Don't return private data in the reply just because the sender's number matches a record.

Considerations

• Use it in API endpoints. It reads the fields of the current request. In a form or a workflow, it reads whatever that request contains, which usually isn't a Twilio message.
• Tokens from the message are untrusted text. [Sms:Body] is whatever the sender typed. Don't insert it directly into SQL, HTML or the reply message. Use SQL parameters, and see TwiML escaping before echoing it back.
• FromZip is always empty. In 1.28, the action reads the wrong field for the sender's ZIP code, so [<Output Token>:FromZip] never has a value.
• Always send a response. End the actions with Twilio Send Response to SMS Webhook, even with empty parameters, so Twilio gets valid TwiML. Otherwise the API returns the text Success, which isn't TwiML, and Twilio logs an error in its Debugger.
• Twilio times out. Twilio waits about 15 seconds for the response. Keep the actions quick, and move slow work to Execute Actions Asynchronously.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Read the incoming SMS

This action goes first in the API endpoint's actions. It creates [Sms:From], [Sms:Body] and the other tokens.

{
    "Title": "Twilio Parse Webhook SMS",
    "ActionType": "TwilioParseWebhook",
    "Description": "Read the incoming SMS",
    "Parameters": {
        "OutputToken": "Sms"
    }
}

2. Reply with a fixed confirmation

Put this action after the one above, and after any actions that save the message. It replies to the sender and ends the webhook call.

{
    "Title": "Twilio Send Response to SMS Webhook",
    "ActionType": "TwilioSendSmsResponse",
    "Description": "Confirm we got the message",
    "Parameters": {
        "ResponseMessage": "Thanks, we got your message. We'll reply soon.",
        "StatusCallbackUrl": "",
        "UseRedirect": false,
        "UrlToRedirectTo": "",
        "UsePOSTForRedirect": false
    }
}

3. Ignore requests that aren't for your account

This action ends the call with an empty TwiML response when the request's Account SID isn't yours. Put it right after the parse action, and replace the placeholder with your own Account SID, for example from a setting token. As explained in Securing the webhook, this isn't a full security check.

{
    "Title": "Twilio Send Response to SMS Webhook",
    "ActionType": "TwilioSendSmsResponse",
    "Description": "Stop if the request isn't for our Twilio account",
    "Condition": "[Sms:AccountSid] != [TwilioAccountSid]",
    "Parameters": {
        "ResponseMessage": "",
        "UseRedirect": false
    }
}

Revised 09/27/2026