Twilio Module

Send SMS, MMS and WhatsApp messages, verify users with one-time codes, and check phone numbers from any workflow.

The Twilio Module holds the standalone Twilio Tasks: they run in any Process, whatever Channel the Session started on (a web chat, a form, a schedule, an API call). It has no Channel of its own. For two-way SMS and WhatsApp conversations and for phone calls, add one of the other Modules of the Twilio family (see Which Twilio module?). The Module requires Environment configuration: each Environment supplies its own Twilio credentials, default senders and Verify service.

The Twilio family

Twilio support is split across four Modules. This page is the core; the three others each add Channels:

• Twilio Module (this page): TwilioSendSmsTask, TwilioSendMmsTask, TwilioSendWhatsAppTask, TwilioLookupNumberTask, TwilioSendOtpTask, TwilioVerifyOtpTask. No Channel.
• Twilio Messaging: SMS and WhatsApp bots on Twilio Programmable Messaging. Channels TwilioMessagingSms and TwilioMessagingWhatsApp, a WhatsApp start and an SMS start, and the WhatsApp buttons Task.
• Twilio Conversations: SMS and WhatsApp on the Twilio Conversations API, with the conversation kept on Twilio. Channels TwilioSms and TwilioWhatsApp, a WhatsApp start and an SMS start.
• Twilio Voice: phone calls (spoken prompts, speech and keypad input, play, record, dial). Channel TwilioVoice and its call start.

Each Module in the family is configured separately: every Module has its own Environment configuration with its own Twilio credentials (Account SID, Auth Token, ...). You can paste the same credentials into each Module, or use a different Twilio account or subaccount per Module. A Process uses a Channel by depending on its Module and by starting with that Channel's start: the WhatsApp and SMS starts put the message that opened the Session in {message}, the call start puts the call in {call}. A Process answering several Channels has one start per Channel, joined right after them; the rest of the flow (OutputTask → InputTask → EndTask) is the same on every Channel. Processes that still begin with the shared Start (Chat / API) keep working as before.

Which Twilio module?

	Twilio Messaging	Twilio Conversations	Twilio Voice
Choose it for	Simple 1:1 SMS and WhatsApp bots	Conversations kept on Twilio: agent handoff (Twilio Flex), several participants, the Conversations chat SDK	Phone calls
Twilio product	Programmable Messaging (Messages API)	Conversations API	Programmable Voice (TwiML)
Channels	TwilioMessagingSms, TwilioMessagingWhatsApp	TwilioSms, TwilioWhatsApp	TwilioVoice
One Session per	Phone number pair (the user's number and yours)	Twilio conversation	Call
Twilio cost	Cheaper: you pay for the messages only	Messages plus Twilio's Conversations charges	Voice minutes
Files	Yes (WhatsApp attachments, SMS download links)	Yes (WhatsApp attachments, SMS download links)	No, text only
What the deploy sets on Twilio	The Messaging Service's Inbound Request URL	The Conversation Service's post-event webhook	The phone number's voice webhook

To send a message without a conversation (a notification, a reminder, a one-time code), you do not need any of them: use the Tasks on this page.

One number, one mode

A Twilio Messaging Service delivers the inbound messages of its numbers to one place: either its own inbound webhook (the Inbound Request URL, used by Twilio Messaging) or Twilio Conversations "autocreate" (used by Twilio Conversations). When the webhook is set, it wins and Conversations never sees the message. So a number, through its Messaging Service, works in one mode at a time:

• The Twilio Messaging deploy points the Messaging Service's Inbound Request URL at its Environment. It refuses when that URL already points at another Environment, because the number belongs to that Environment.
• The Twilio Conversations deploy reports an error when its Messaging Service sends inbound messages to the Twilio Messaging Module, unless Clear Messaging Service Inbound Webhook on Deploy is on (which moves the service back to Conversations).

To run both modes, use two Messaging Services with their own numbers.

Moving from the old Twilio Module

Before the split, the Twilio Module also carried the voice, SMS and WhatsApp Channels. They now live in the satellite Modules:

Channel or Tasks	Now in
TwilioVoice, TwilioVoicePlayTask, TwilioVoiceRecordTask, TwilioVoiceDialTask	Twilio Voice
TwilioSms, TwilioWhatsApp (Conversations API)	Twilio Conversations
New: TwilioMessagingSms, TwilioMessagingWhatsApp (Programmable Messaging)	Twilio Messaging

The Channel names and the webhook URLs did not change. To keep a Process working on one of these Channels:

1. Add the Module (Twilio Voice or Twilio Conversations) to the Process. A Process that already contains voice Tasks gets Twilio Voice as a dependency automatically.
2. Fill the Module's Environment configuration. Credentials are entered per Module: copy the Account SID and Auth Token into the new Module too. The voice settings (Phone section) and the Conversation Service settings (SMS and WhatsApp sections) are no longer in the Twilio Module's configuration.
3. Redeploy. With the Module's Auto-Deploy toggle on, the deploy sets the Twilio webhook again.

The Twilio Module keeps the Send, Verify and Lookup Tasks and their settings (default senders and Verify service).

Quick start (send an SMS)

1. Create a Twilio account. Note the Account SID (AC...) and Auth Token on the Console dashboard.
2. Buy a Twilio number that can send SMS: Console → Phone Numbers → Buy a Number.
3. Configure the Module. Open Environments, select your Environment, and open the Twilio Module configuration: fill Account SID and Auth Token, then in the SMS Configuration section set Default From Number to your number (E.164, for example +15551230000).
4. Add a TwilioSendSmsTask to any Process: To = {phone}, Body = Your order {orderId} has shipped.
5. Deploy and run the Process. The recipient gets the text.

For conversations (the user writes back), use Twilio Messaging or Twilio Conversations instead.

Configuration

Configuration is per Environment: each Environment supplies its own Twilio credentials and SIDs. Open Environments, select the Environment, and open the Twilio Module configuration. The form has the credentials at the top followed by three sections: SMS, WhatsApp and Verify.

Core Credentials

Every Module of the Twilio family has these four fields at the top of its own configuration; they are described here once.

Field	Type	Required	Description
Account SID	string (secret)	Yes	Twilio Account SID (AC...)
Auth Token	string (secret)	Yes	Twilio Auth Token
Webhook Signing Secret	string (secret)	No	Optional override key for webhook signature checks
Validate Signatures	boolean	No (default: on)	Verify the signature on every inbound Twilio webhook

Account SID

Twilio Account SID, starts with AC. Find it on the Twilio Console main dashboard under Account Info. Example: ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Required. Stored as a secret. Each Module of the family stores its own copy.

Auth Token

Twilio Auth Token, next to the Account SID on the Console dashboard. Used to authenticate Twilio API calls and to verify the signature on inbound webhooks.

Required. Stored as a secret.

Webhook Signing Secret

Optional override for webhook signature verification. Default: empty (the Auth Token is used).

Set it only if you rotate your Auth Token but want a separate key for webhook signing. The Twilio Module itself receives no webhooks; this field matters on Twilio Messaging, Twilio Conversations and Twilio Voice.

Validate Signatures

When on, every inbound Twilio webhook is rejected with 403 if the X-Twilio-Signature header doesn't match. When off, the engine accepts any request. Default: on.

Leave it on in shared Environments. Disable it only for local debugging: in Production the check is always enforced, even if this toggle is off. Like the signing secret, it only matters on the Modules that receive webhooks.

---

SMS Configuration

Default sender of TwilioSendSmsTask and TwilioSendMmsTask.

Field	Type	Required	Description
Default From Number	string	No	Fallback sender number for outbound SMS/MMS
Messaging Service SID	string	No	Twilio Messaging Service (MG...) used in place of a From number

Default From Number

Fallback sender phone number in E.164 format (for example +1234567890). Used by TwilioSendSmsTask / TwilioSendMmsTask when the Task omits the From field. Default: empty.

Must be a verified Twilio number on your account.

Messaging Service SID

Optional Twilio Messaging Service SID, starts with MG. When set, it is used in place of From for outbound SMS (automatic number pooling, sticky sender and opt-out management). Default: empty.

Where to find it: Twilio Console → Messaging → Services → your service.

Sending through a Messaging Service does not change where its inbound messages go: that is decided by Twilio Messaging or Twilio Conversations (see One number, one mode).

---

WhatsApp Configuration

Default sender of TwilioSendWhatsAppTask.

Field	Type	Required	Description
WhatsApp From Number	string	No	Default sender for outbound WhatsApp

WhatsApp From Number

Default sender for TwilioSendWhatsAppTask. Must include the whatsapp: prefix. Default: empty.

Example: whatsapp:+14155238886 (the Twilio WhatsApp sandbox number).

For production, use your approved WhatsApp Business number.

---

Verify (OTP) Configuration

Field	Type	Required	Description
Verify Service SID	string	For OTP Tasks	Twilio Verify Service (VA...)

Verify Service SID

Twilio Verify Service SID, starts with VA. Required by TwilioSendOtpTask and TwilioVerifyOtpTask. Example: VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Where to find it: Twilio Console → Verify → Services → your service. Create a new one if you don't have one.

---

Tasks

All Tasks in this Module are Generic: they run in any Process regardless of how it started (any Channel: Chat, Web, a Twilio Session, a schedule, ...). They need no inbound call or message, only valid credentials in the Module's Environment configuration. The Tasks that only run during a call are on the Twilio Voice page.

Several Tasks below have a Store variable output: a field where you type a variable name (no braces). The Task saves its result there and later Tasks can reference it as {name}.

TwilioSendSmsTask (Generic)

Send a one-shot outbound SMS: fire-and-forget, no conversation needed.

Use it for: notifications, alerts, magic-link delivery, anywhere you want to push a single SMS without expecting a reply.

Properties

Property	Type	Required	Example	Description
From	string	No	+15551230000	Sender number in E.164 format. Default: empty (falls back to the Environment's Default From Number or Messaging Service SID).
To	string	Yes	{phone}	Recipient in E.164 format. Supports {variable} placeholders.
Body	string	Yes	Hi {execution.channelSender}, your order shipped.	SMS text. Supports {variable} placeholders.
StatusCallbackUrl	string	No	https://example.com/sms-status	Twilio delivery-status callback URL. Default: empty.
OutputVariable	Store variable	No	smsSid	Variable name (no braces) that receives the Twilio message ID; later Tasks read it as {smsSid}. Default: empty (the ID is not stored).

Example

A Process triggered by an API call sets {phone} and {orderId}, then a TwilioSendSmsTask with To = {phone}, Body = Order {orderId} has shipped. delivers the text. If Twilio rejects the request (invalid number, unverified sender), the Task routes to its error output with error 4001.

TwilioSendMmsTask (Generic)

Send an outbound SMS with one or more media attachments (image, audio, video, document).

Use it for: delivering boarding passes, receipts with logos, photo confirmations. MMS is delivered only to US and Canadian numbers; elsewhere, send a link in a plain SMS.

Properties

Property	Type	Required	Example	Description
From	string	No	+15551230000	Sender number. Default: empty (falls back to the Environment's Default From Number or Messaging Service SID).
To	string	Yes	+15557654321	Recipient in E.164 format.
Body	string	No	Your receipt is attached.	Optional caption text. Default: empty.
MediaUrls	string	Yes	https://cdn.example.com/receipt.pdf	One absolute http:// or https:// URL per line (or comma-separated). Twilio fetches each URL from the public internet, so localhost and private addresses are rejected up front. Each URL must return 200 with a supported content type (image/jpeg, image/png, image/gif, video/mp4, application/pdf, ...).
OutputVariable	Store variable	No	mmsSid	Variable name (no braces) that receives the Twilio message ID. Default: empty.

Example

MediaUrls = https://cdn.example.com/boardingpass/{bookingRef}.png, To = {phone}: the recipient gets an MMS with the rendered boarding pass. If Twilio can't fetch or accept a URL, the error log includes the failing Twilio code and the full media URL list, so a 12300 (unsupported content type) or 11200 (fetch failure) tells you immediately which URL failed.

TwilioSendWhatsAppTask (Generic)

Send an outbound WhatsApp message: free-form within the 24-hour session window, or an approved template outside it.

Use it for: customer support replies, order updates, appointment reminders.

Properties

Property	Type	Required	Example	Description
From	string	No	whatsapp:+14155238886	Sender. Default: empty (falls back to the Environment's WhatsApp From Number). The whatsapp: prefix is added automatically if missing.
To	string	Yes	{phone}	Recipient. The whatsapp: prefix is added automatically if missing.
Body	string	Conditional	Your order {orderId} is on its way!	Free-form message. Required when ContentSid is empty. Only allowed inside the 24-hour session window.
ContentSid	string	Conditional	HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx	Approved WhatsApp template SID. Required when Body is empty.
ContentVariables	string	No	{"1":"Maria","2":"Tuesday"}	JSON-encoded template variable map, used with ContentSid. Default: empty.
MediaUrls	string	No	https://cdn.example.com/photo.jpg	Newline- or comma-separated public URLs. Default: empty.
OutputVariable	Store variable	No	waSid	Variable name (no braces) that receives the Twilio message ID. Default: empty.

The Task fails with error 3005 if neither Body nor ContentSid is set.

WhatsApp 24-hour session window

WhatsApp only allows free-form Body messages within 24 hours of the user's last inbound message. Outside the window, send an approved template via ContentSid. New templates must be submitted through Twilio for WhatsApp approval before they can be used.

TwilioLookupNumberTask (Generic)

Validate a phone number with Twilio Lookup and store the verdict in Session variables.

Use it for: rejecting landlines from SMS-only workflows, detecting SIM swap before sending an OTP, displaying the carrier or caller name.

Properties

Property	Type	Required	Example	Description
PhoneNumber	string	Yes	+442071234567	E.164 number to look up. Supports {variable} placeholders.
Fields	string	No	line_type_intelligence,sim_swap	Comma-separated Lookup add-ons: line_type_intelligence, caller_name, sim_swap, call_forwarding, identity_match. Some incur per-lookup charges. Default: empty (basic validation only).
OutputPrefix	string	No	lookup	Prefix for the result variables: {lookup.valid}, {lookup.countryCode}, {lookup.lineTypeIntelligence.type}, etc. Default: lookup.

Example

PhoneNumber = {phone}, Fields = line_type_intelligence: afterwards {lookup.valid} is true/false and {lookup.lineTypeIntelligence.type} says mobile, landline, or voip, ready for a SwitchTask. Invalid numbers return {lookup.valid} = false without failing the Task; API errors also set {lookup.error} with the reason.

TwilioSendOtpTask (Generic)

Send a Twilio Verify one-time code over SMS, voice call, email, or WhatsApp.

Use it for: the first half of a two-factor verification. Pair with TwilioVerifyOtpTask.

Properties

Property	Type	Required	Example	Description
To	string	Yes	+15557654321	Phone number (for sms / call / whatsapp) or email address (for email).
Channel	string	Yes	sms	Delivery channel: sms, call, email, or whatsapp. Default: sms.
Locale	string	No	it	IETF language tag for the OTP message (en, it, fr, ...). Default: empty (Twilio picks the language).
OutputSidVariable	Store variable	No	verifySid	Variable name (no braces) that receives the verification ID. Default: empty.

Requires Verify Service SID in the Module's Environment configuration, otherwise the Task fails with error 4008.

TwilioVerifyOtpTask (Generic)

Check a one-time code submitted by the user against Twilio Verify.

Use it for: the second half of a two-factor verification. Wire a SwitchTask after it to branch on the status variable.

Properties

Property	Type	Required	Example	Description
To	string	Yes	{phone}	The same identifier used when sending the code.
Code	string	Yes	{code}	The code entered by the user. Supports {variable} placeholders.
OutputStatusVariable	Store variable	No	otpStatus	Variable name (no braces) that receives the verification status: approved, pending, or canceled. Default: empty.

When the status is anything other than approved, the Task routes to its error output and logs error 4021.

Common recipes

Verify a user's phone number with a one-time code

Send an OTP to the number the user provides, then branch on whether the code checks out. This works on any Channel, for example the web chat.

1. InputTask (Standard Module): prompt "What's your phone number?", Variable = phone.
2. TwilioSendOtpTask: To = {phone}, Channel = sms, OutputSidVariable = verifySid. The user receives a code by SMS. Requires Verify Service SID in the Environment configuration.
3. InputTask: prompt "Enter the code we sent you", Variable = code.
4. TwilioVerifyOtpTask: To = {phone}, Code = {code}, OutputStatusVariable = otpStatus.
5. SwitchTask: Variable = {otpStatus}, routes approved / everything else.
6. On the approved Sequence Flow: OutputTask "You're verified!". On the other branch: OutputTask "That code didn't match. Please try again."

For an SMS or WhatsApp bot that answers the user's messages, see the recipes on Twilio Messaging and Twilio Conversations.

Troubleshooting

A Send Task fails with error 4001

Twilio rejected the request. The error message carries Twilio's code and text. The most common causes: the From number is not a number of your account (or not enabled for SMS / WhatsApp), the recipient is not in E.164 format, or a WhatsApp Body was sent outside the 24-hour window.

A Send Task fails with error 4008

Account SID or Auth Token is empty in this Module's configuration, or (for the OTP Tasks) Verify Service SID is empty. Remember that each Module of the family has its own configuration: credentials entered on Twilio Messaging or Twilio Voice are not used by the Twilio Module.

Webhook returns 403

This applies to the Modules that receive webhooks (Messaging, Conversations, Voice). The engine rejects the request when:

• That Module has no configuration in the Environment the URL belongs to (each Module is configured separately), or
• Validate Signatures = on and the URL registered on Twilio doesn't match the URL the engine sees (for example http vs https, or a stale tunnel URL), or
• The Auth Token (or Webhook Signing Secret) in that Module's configuration doesn't match the one Twilio is signing with.

For local debugging only, toggle Validate Signatures = off to confirm the rest of the workflow works, then re-enable.

Reference

Modules and Channels

Module	Module ID	Channels
Twilio Module	TwilioModule	none
Twilio Voice	TwilioModule.Voice	TwilioVoice (call start, {call})
Twilio Conversations	TwilioModule.Conversations	TwilioSms, TwilioWhatsApp (SMS / WhatsApp start, {message})
Twilio Messaging	TwilioModule.Messaging	TwilioMessagingSms, TwilioMessagingWhatsApp (SMS / WhatsApp start, {message})

WhatsApp notes

WhatsApp has constraints that apply to every Module of the family:

• Sandbox onboarding: users must first text the "join code" to the sandbox number before they can receive anything.
• 24-hour session window: free-form messages are only allowed within 24 hours of the user's last inbound message. Outside the window, use ContentSid on TwilioSendWhatsAppTask to send an approved template. Replies sent by an OutputTask on a WhatsApp Channel are free-form, so they only reach the user inside the window.
• Template approval: new message templates must be submitted for WhatsApp approval through Twilio before they can be sent.
• Buttons: to ask a question with tappable answers inside a conversation, use TwilioWhatsAppButtonsTask with an approved template that has quick-reply buttons; the tapped button lands in a variable for a SwitchTask to route on.

See also WhatsApp compliance.

Gotchas

Italian SMS carrier rewrites

For recipients on Italian carriers, the operator's SMS gateway may rewrite the sender on the downstream leg and deliver the message from a shared short code instead of the long code it was sent from. The end user sees the message arriving from a short code and, if they try to reply to it, gets the carrier template "Can't reply to this short code".

This happens even when you send from a long code (a Messaging Service pool with only long codes, or a fixed From number): the rewrite happens downstream of Twilio. It hurts most on two-way SMS (Twilio Messaging, Twilio Conversations), because the user cannot answer. Fixes:

• Register the Italian long code for A2P (Twilio Console → Messaging → Regulatory Compliance).
• Or steer the conversation over WhatsApp (whatsapp:+… is not subject to the rewrite).

Short-code entries in the Messaging Service pool

If your Messaging Service sender pool contains an actual US / international short code in addition to the long code, Twilio may pick the short code for some messages (a TwilioSendSmsTask through the Messaging Service, or a reply on Twilio Conversations) even when the user wrote to the long code. Remove the short code from the pool, or enable Sticky Sender on the Messaging Service so later messages to a user stay on whichever sender was used first.

Best practices

1. Keep Validate Signatures on in the Modules that receive webhooks: it's the only thing standing between your webhooks and forged requests; disable it only briefly for local debugging.
2. Use a Messaging Service for outbound SMS: number pooling, sticky sender, and opt-out handling come for free, and you stop hardcoding From numbers in Tasks.
3. Gate OTP sends with a number lookup: run TwilioLookupNumberTask first and branch on {lookup.valid} to avoid paying for Verify attempts to landlines and invalid numbers.
4. Use templates outside the WhatsApp window: set ContentSid on TwilioSendWhatsAppTask for any message that might land more than 24 hours after the user's last reply.
5. Pick one mode per number: decide per Messaging Service whether its numbers run on Twilio Messaging or Twilio Conversations (One number, one mode).

Error codes

The Twilio failure modes map to these codes; see the full reference for resolutions:

Code	Name	Description
3005	TaskInvalidData	A Task is missing required data (for example TwilioSendWhatsAppTask with neither Body nor ContentSid)
4001	ModuleException	Twilio rejected an API request (invalid number, unverified sender, bad media URL, ...)
4008	ModuleMissingConfiguration	Account SID, Auth Token, or a required service SID is not set in the Environment configuration
4020	WebhookSignatureInvalid	An inbound webhook (Messaging, Conversations, Voice) failed the signature check
4021	OtpNotApproved	Twilio Verify returned a status other than approved