Twilio twilio

When to Use

• OTP and 2FA delivery: Send a one-time password via SMS as part of a multi-factor authentication workflow, with the code drawn from a previous node's output.
• Appointment reminders: Trigger an SMS or voice call reminder 24 hours before a scheduled appointment using a date-based expression in the message field.
• Order status notifications: Notify a customer by SMS when their order ships, is out for delivery, or requires action, using {{ $output.order.phone }} as the destination number.
• Emergency alerts: Place automated voice calls to an on-call roster when a monitoring workflow detects a critical failure, using the call/make operation with a spoken TwiML message.
• Automated voice surveys: Initiate outbound calls that collect voice input via TwiML <Gather>, routing callers through a decision tree and recording responses for downstream processing.

Configuration

Credentials (both operations)

Operation: sms/send

Operation: call/make

Sample Configuration JSON — SMS Send

{
  "resource": "sms",
  "operation": "send",
  "accountSid": "{{ $credentials.twilio-account-sid }}",
  "authToken": "{{ $credentials.twilio-auth-token }}",
  "from": "+14155558888",
  "to": "{{ $output.customer.phone }}",
  "message": "Your order #{{ $output.order.id }} has shipped. Track it at https://track.mystore.com/{{ $output.order.trackingCode }}",
  "statusCallback": "https://app.mycompany.com/webhooks/sms-status"
}

Sample Configuration JSON — Call Make

{
  "resource": "call",
  "operation": "make",
  "accountSid": "{{ $credentials.twilio-account-sid }}",
  "authToken": "{{ $credentials.twilio-auth-token }}",
  "from": "+14155558888",
  "to": "{{ $output.oncall.phone }}",
  "message": "Alert: Production API error rate has exceeded 5 percent. Please acknowledge within 10 minutes.",
  "useTwiml": false,
  "statusCallback": "https://app.mycompany.com/webhooks/call-status"
}

Validation Errors

Output

sms/send — Success Port

call/make — Success Port

Error Port

Fires when Twilio returns an error response (invalid number format, insufficient account balance, invalid credentials, unverified destination number in trial mode, or unsupported resource/operation combination). The error output contains errorCode and message fields.

Sample Output JSON — sms/send

{
  "messageSid": "SM3f4a2b1c8d9e0f1a2b3c4d5e6f7a8b9c4",
  "to": "+14155552671",
  "from": "+14155558888",
  "messageStatus": "queued",
  "numSegments": 1,
  "price": "",
  "priceUnit": "USD",
  "twilioErrorCode": null,
  "twilioErrorMessage": ""
}

Expression Reference

Node Policies & GuardRails

• Store credentials in Credentials Manager. Never embed raw accountSid or authToken values in node configuration. Use {{ $credentials.name }} references. The Auth Token grants full account access and must be treated as a secret.
• Use E.164 format for all phone numbers. Numbers not in E.164 format (e.g. missing +, local format) will be rejected by Twilio with a 21211 error. Validate numbers in a preceding Data Mapping node when the number comes from user input.
• Verify destination numbers in trial accounts. Twilio trial accounts can only send to verified phone numbers. Unverified numbers will cause a 21608 error. Upgrade to a paid account for production use.
• XML-encode TwiML content when using useTwiml: false. When plain text mode is active (the default), the executor handles XML encoding. When useTwiml: true, the caller owns safety — validate and sanitise any user-supplied content before passing it as TwiML.
• Monitor numSegments for cost control. Each additional 160-character segment is billed as a separate message. Pre-truncate or paginate long messages in an upstream node when per-message cost is a concern.
• Set statusCallback for delivery audit trails. The success port only confirms that Twilio accepted the request. For compliance or retry workflows, configure a statusCallback endpoint that ingests delivery events and persists them.

Examples

OTP Delivery — Two-Factor Authentication

{
  "resource": "sms",
  "operation": "send",
  "accountSid": "{{ $credentials.twilio-account-sid }}",
  "authToken": "{{ $credentials.twilio-auth-token }}",
  "from": "+14155558888",
  "to": "{{ $output.user.phoneNumber }}",
  "message": "Your BizFirstAI verification code is {{ $output.auth.otp }}. It expires in 5 minutes. Do not share this code."
}

The OTP generated by an upstream Code Execute node is injected into the message body via expression. No statusCallback is needed here — the success port confirming queued is sufficient before moving to the wait state.

Emergency Voice Alert — On-Call Paging

{
  "resource": "call",
  "operation": "make",
  "accountSid": "{{ $credentials.twilio-account-sid }}",
  "authToken": "{{ $credentials.twilio-auth-token }}",
  "from": "+14155558888",
  "to": "{{ $output.oncall.primaryPhone }}",
  "message": "Critical alert from BizFirstAI. Service {{ $output.alert.serviceName }} is down. Incident ID {{ $output.alert.incidentId }}. Please acknowledge by pressing any key.",
  "useTwiml": false,
  "statusCallback": "https://ops.mycompany.com/webhooks/call-ack"
}

The plain-text message is XML-encoded and wrapped in a <Say> TwiML verb by the executor. The statusCallback receives the final call status so the incident workflow can escalate to the secondary on-call contact if the call goes unanswered.

WhatsApp Order Notification

{
  "resource": "sms",
  "operation": "send",
  "accountSid": "{{ $credentials.twilio-account-sid }}",
  "authToken": "{{ $credentials.twilio-auth-token }}",
  "from": "+14155558888",
  "to": "{{ $output.order.customerPhone }}",
  "message": "Hi {{ $output.order.customerName }}, your order #{{ $output.order.id }} is out for delivery today. Estimated arrival: {{ $output.order.eta }}.",
  "toWhatsapp": true
}

Setting toWhatsapp: true routes the message through WhatsApp instead of the SMS network. The from number must be a Twilio WhatsApp-approved sender. The message content must comply with WhatsApp Business messaging policies.