Event

trigger.twilio_event

TriggerVoice & SMSconnection requiredruns in-engine

Points a Twilio phone number's or messaging service's inbound webhook at Mantle on publish and starts one run per callback, verified against Twilio's signature over the URL and the sorted POST parameters.

Start a run when Twilio calls back about an inbound message or call. Twilio has no webhook subscriptions, so publishing REWRITES the webhook URL on the chosen phone number or messaging service in the tenant's own Twilio account — replacing whatever was configured there — and disabling or unpublishing puts the previous value back.

Ask about Twilio All Twilio nodes Provider API docs ↗

Connection

Required: Yes — the node will not save without one
Auth type: Username & password
Providers: Twilio
Secret shape: the Twilio account_sid and auth_token
Resolved by: config.connection_id, else node.connection_id
Note: The credentials must be able to update the phone number or messaging service — a restricted API key that can only send messages will fail to publish. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to an https URL Twilio can reach.

Configuration

2 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
target_sid The phone number (PN…) or messaging service (MG…) whose inbound webhook should point at Mantle. PUBLISHING OVERWRITES that webhook URL in the tenant's Twilio account; the previous value is restored when the workflow is disabled or unpublished.	string	Yes	—	matches ^(PN\|MG)[0-9a-fA-F]{32}$	PN0a1b2c3d4e5f60718293a4b5c6d7e8f9
channel Which webhook slot to take over: 'message' writes SmsUrl on a number or InboundRequestUrl on a messaging service; 'voice' writes VoiceUrl and is only available on a phone number.	string	No	message	one of "message", "voice"	—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "channel": "message",
  "target_sid": "PN0a1b2c3d4e5f60718293a4b5c6d7e8f9"
}

Output

One shape.

twilio callback

The flattened Twilio callback. Which parameters arrive depends on the channel and the message type, so the shape is open below the declared fields and params carries all of them.

Extra keys beyond the ones listed can appear.

Field	Type	Example
id Twilio's MessageSid (SM…/MM…) or CallSid (CA…). Part of the idempotency key: a retry of the same callback carries the same SID and status, so it joins the run it already started instead of starting a second.	string	SM0123456789abcdef0123456789abcdef
kind 'message' when the callback carries a MessageSid, 'voice' when it carries a CallSid. Empty for a callback that carries neither.	string	message
account_sid The Twilio account (AC…) the callback came from.	string	—
from The sender — an E.164 number, or a whatsapp:+… address on WhatsApp.	string	+15551230000
to The Twilio number or address that received it.	string	+15559874444
body The message text, empty on a voice callback or a media-only MMS.	string	STOP
status MessageStatus / SmsStatus on a message ('received', 'delivered', 'failed'…) or CallStatus on a call ('ringing', 'completed'…).	string	received
num_media How many media parts the message carries (Twilio's NumMedia).	number	0
media One entry per attachment: its Twilio-hosted url and content_type. Empty unless num_media is above zero.	array	—
messaging_service_sid The messaging service (MG…) that handled the message, when one did.	string	—
params Every form parameter Twilio sent, verbatim — the geo fields, the WhatsApp profile name, button payloads and everything else this contract does not lift out. Keys are Twilio's PascalCase names.	object	—

{
  "account_sid": "AC0123456789abcdef0123456789abcdef",
  "body": "STOP",
  "from": "+15551230000",
  "id": "SM0123456789abcdef0123456789abcdef",
  "kind": "message",
  "media": [],
  "messaging_service_sid": "",
  "num_media": 0,
  "params": {
    "Body": "STOP",
    "From": "+15551230000",
    "FromCountry": "US",
    "MessageSid": "SM0123456789abcdef0123456789abcdef",
    "To": "+15559874444"
  },
  "status": "received",
  "to": "+15559874444"
}

Notes

Publishing CHANGES CONFIGURATION IN THE CUSTOMER'S TWILIO ACCOUNT: the chosen webhook URL is replaced, and whatever was receiving those callbacks stops. Disabling or unpublishing restores the old value.
The restore is skipped if somebody re-pointed the number in the Twilio console after Mantle did — Mantle never overwrites a later human change.
One number or messaging service feeds one workflow per channel. A second workflow published against the same target takes the callback away from the first.
The callback method is forced to POST: Twilio's signature is only defined for the form-encoded POST body.
Twilio answers the run with an empty 202, not TwiML — this trigger starts a workflow, it does not reply to the sender. Send a reply with twilio.send_sms if you need one.

Related Twilio nodes

See Event run in a workflow.

In a technical demo we add the Twilio connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales