Twilio SMS Webhook TypeScript Types (Inbound SMS)
TypeScript interfaces for the Twilio inbound SMS webhook payload. Use these types to handle incoming text messages in your Twilio application.
Twilio SMS Webhook — Sample JSON
{
"ToCountry": "US",
"ToState": "CA",
"SmsMessageSid": "SM1234567890abcdef1234567890abcdef",
"NumMedia": "0",
"ToCity": "SAN FRANCISCO",
"FromZip": "10001",
"SmsSid": "SM1234567890abcdef1234567890abcdef",
"FromState": "NY",
"SmsStatus": "received",
"FromCity": "NEW YORK",
"Body": "Hello from Twilio!",
"FromCountry": "US",
"To": "+14155551234",
"ToZip": "94105",
"NumSegments": "1",
"MessageSid": "SM1234567890abcdef1234567890abcdef",
"AccountSid": "AC1234567890abcdef1234567890abcdef",
"From": "+12125551234",
"ApiVersion": "2010-04-01"
}Generated TypeScript
export interface TwilioInboundSms {
ToCountry: string;
ToState: string;
SmsMessageSid: string;
NumMedia: string;
ToCity: string;
FromZip: string;
SmsSid: string;
FromState: string;
SmsStatus: string;
FromCity: string;
Body: string;
FromCountry: string;
To: string;
ToZip: string;
NumSegments: string;
MessageSid: string;
AccountSid: string;
From: string;
ApiVersion: string;
}How to use
Copy the TypeScript above into a types.ts file in your project. Import the root interface and use it to type your API responses: const data: TwilioInboundSms = await res.json()
Working with a different JSON payload? Paste any JSON and generate TypeScript interfaces instantly.
Convert your own JSON →FAQ
Why are numeric fields like NumMedia typed as string in the Twilio webhook?
Twilio sends all webhook parameters as form-encoded strings (application/x-www-form-urlencoded), not JSON. Even fields that look numeric — NumMedia, NumSegments — arrive as strings. You need to parseInt() them if you need numeric operations.
How do I validate that a Twilio webhook request is genuine?
Twilio signs every webhook request with an X-Twilio-Signature header using your account's AuthToken. Compute the HMAC-SHA1 of the full request URL + sorted parameters using your AuthToken as the key. If it matches the header, the request is authentic.
Does NumMedia > 0 mean there are images attached?
Yes. When NumMedia is '1' or higher, Twilio adds MediaUrl0, MediaUrl1, etc. and MediaContentType0, MediaContentType1, etc. parameters to the webhook body. These are not present in the type definition above since this sample has NumMedia: '0'.