Docs / Strand / connectors/twilio

Twilio Connector

Send SMS and MMS messages via the Twilio API from your Strand workflows.

Prerequisites

You need a Twilio account with messaging capabilities:

Sign up at twilio.com and verify your account
From the Twilio Console, note your:

Account SID (starts with AC)
Auth Token

Get a phone number:

Buy a Twilio phone number from Phone Numbers > Manage > Buy a number, or
Set up a Messaging Service from Messaging > Services for higher-volume sending

Tip: Use a Messaging Service for production workloads. It handles sender selection, compliance, and scaling automatically.

Required Permissions

Your Twilio account must have:

Requirement	Description
Active account	Twilio account must be active (not suspended)
Messaging capability	The sending phone number or Messaging Service must support SMS
Verified recipients (trial)	Trial accounts can only send to verified phone numbers

Connector Setup

Create a Twilio connector from the Connectors page.

Configuration Fields

Field	Required	Description
Name	Yes	Friendly name (e.g., "Production Twilio")
Account SID	Yes	Twilio Account SID (starts with `AC`)
Auth Token	Yes	Twilio Auth Token (encrypted at rest)
From Phone	No*	Default sender phone number in E.164 format (e.g., `+15551234567`)
Messaging Service SID	No*	Twilio Messaging Service SID (starts with `MG`)
Timeout	No	Request timeout in seconds (default: 30)
Description	No	Optional description for reference

*Either From Phone or Messaging Service SID must be configured. If both are provided, both are sent to Twilio (Messaging Service takes precedence).

Operations

Send SMS

Send an SMS or MMS message to a phone number.

Field	Required	Description
To	Yes	Recipient phone number in E.164 format (e.g., `+15559876543`)
Body	Yes	Message text (supports Jinja2 templating)
Media URL	No	URL of media to attach (sends as MMS)

Example: Send an order confirmation:

To: {{ payload.customer_phone }}
Body: Your order #{{ payload.order_id }} has been confirmed and will ship by {{ payload.ship_date }}.

Example: Send an MMS with image:

To: {{ payload.phone }}
Body: Here's your receipt for order #{{ payload.order_id }}
Media URL: {{ payload.receipt_image_url }}

Output

json


{
  "success": true,
  "status": "queued",
  "to": "+15559876543",
  "from": "+15551234567",
  "body": "Your order #ORD-123 has been confirmed.",
  "data": {
    "sid": "SM1234567890abcdef1234567890abcdef",
    "status": "queued",
    "date_created": "Thu, 12 Mar 2026 14:30:00 +0000",
    "price": null,
    "num_segments": "1"
  }
}

Key fields for subsequent nodes:

{{ steps.node_a1b2c3d4.output_payload.data.sid }}: Twilio message SID for tracking
{{ steps.node_a1b2c3d4.output_payload.data.status }}: Delivery status (queued, sent, delivered, failed)
{{ steps.node_a1b2c3d4.output_payload.success }}: Whether the API call succeeded

Errors

Error	Meaning
account_sid is missing from connector configuration	Account SID not configured in connector.
auth_token is missing from connector configuration	Auth Token not configured in connector.
'to' phone number is required	No recipient phone number specified in the node.
Message 'body' is required	No message body provided.
Either 'from_phone' or 'messaging_service_sid' must be configured	Neither a sender number nor Messaging Service is set on the connector.
Twilio API error (HTTP 401)	Invalid Account SID or Auth Token.
Twilio API error (HTTP 21211)	Invalid "To" phone number.
Twilio API error (HTTP 21608)	The "From" number is not a valid Twilio number.
Twilio API request timed out	Request exceeded the configured timeout. Check network connectivity.
Failed to connect to Twilio API	Network error reaching Twilio. Check connectivity.

Example Workflow

Create Connector with your Account SID, Auth Token, and From Phone number
Trigger on a new order event
Send SMS to the customer:

To: {{ payload.customer_phone }}
Body: Hi {{ payload.customer_name }}, your order #{{ payload.order_id }} is confirmed!

Logic node to check order value, then conditionally:

Send SMS to the sales team for high-value orders:
To: +15551112222
Body: High-value order #{{ payload.order_id }} (${{ payload.total }}) from {{ payload.customer_name }}

Limitations

SMS/MMS only: Voice calls, WhatsApp, and other Twilio channels are not currently supported.
Single recipient: Each Send SMS operation sends to one phone number. Use a forEach loop for bulk sending.
No delivery webhooks: Twilio status callbacks (delivery receipts) are not supported. Use the message SID to check status via external means if needed.
Trial accounts: Twilio trial accounts can only send to verified phone numbers.
MMS availability: MMS is only available in the US and Canada. International messages are SMS-only.

← Back to Strand docs