Skip to content

Twilio SMS

Twilio SMS delivery. Registers an SMS delivery strategy named twilio with the notification module's strategy pool, sending texts through the Twilio REST API (POST /2010-04-01/Accounts/{AccountSid}/Messages.json with HTTP basic auth). Once selected as the active SMS provider it carries both templated SMS notifications and the SMS one-time codes used for two-factor login.

At a glance
Extension id twilio
Category communication
Version 0.0.1
Provides SMS delivery strategy (twilio)
External account Twilio — Account SID + Auth Token (required)

What It Provides

  • SMS delivery strategy — TwilioSmsStrategy (ext_twilio/strategy.py), an implementation of the core SmsDeliveryStrategy interface, registered as twilio via register_sms_strategy("twilio", TwilioSmsStrategy) on activation. Registration is claimed in the registration ledger — see Notification SMS in Building Extensions.
  • Two core code paths use the active SMS strategy: the notification service's send_sms (renders a notification template, strips HTML tags to plain text, and logs the result to notification_logs) and the two-factor auth service's SMS OTP sender (6-digit verification codes).
  • Nothing else — no webhook endpoints, Temporal workflows, schedules, admin pages, GraphQL fields, or event subscriptions.

Setup

  1. Once installed (or dev-linked in development), the extension is discovered at startup. It uses httpx, which is a core dependency — no extra install is needed.
  2. Enable the extension for a channel from Settings > Extensions (per-channel activation via ChannelExtension).
  3. Make it the active SMS provider by setting the sms_provider platform setting to a JSON object naming the strategy and its credentials, e.g. {"provider": "twilio", "account_sid": "AC…", "auth_token": "…", "from_number": "+15551234567"}. The notification and two-factor services read this setting at send time.
  4. Provide a sender: either from_number or messaging_service_sid. When both are present, messaging_service_sid wins; when neither is configured (and the message itself carries no from number), the send fails immediately with Configure from_number or messaging_service_sid, or set SmsMessage.from_number.

Configuration Reference

Key Type Required Secret Description
account_sid string Yes No —
auth_token string Yes Yes —
from_number string No No —
messaging_service_sid string No No —

Note

This schema drives the generic Configure form on Settings > Extensions. The credentials actually used at send time come from the sms_provider platform setting — the notification service does not read the per-channel extension config when building the strategy. For Twilio the setting keys match the schema keys above.

Operational Notes

  • Send-time construction. The strategy is rebuilt from the sms_provider setting on every send: the setting's keys (minus provider) are passed as constructor arguments — account_sid, auth_token, from_number, messaging_service_sid. If the setting is missing, names an unknown provider, or construction fails, delivery silently falls back to the console (dev logging) strategy.
  • Request shape. Sends are form-encoded with To and Body, plus MessagingServiceSid (preferred) or From, authenticated with HTTP basic auth (account_sid / auth_token), with a 30-second HTTP timeout. The Twilio message sid from the response is recorded as the message id; Twilio's message error field is surfaced on failure.
  • Batch sends are sequential. send_batch loops over single sends.
  • Templated SMS sends are recorded in notification_logs (channel sms) with the provider, message id, recipient, and the first 500 characters of the rendered body.
  • Alternative SMS providers: the built-in console strategy ships with core; Amazon SNS is available as another extension.