Twilio

Twilio is a built-in Norq SMS provider. It builds requests for the POST /2010-04-01/Accounts/{AccountSid}/Messages.json endpoint.

Configuration

providers:
  twilio:
    config:
      account_sid: ${TWILIO_ACCOUNT_SID}
      api_key_sid: ${TWILIO_API_KEY_SID}
      api_key_secret: ${TWILIO_API_KEY_SECRET}
      from: "+15551234567"          # E.164 sender
      # OR
      # messaging_service_sid: MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
      # Optional
      status_callback: https://hooks.example.com/twilio
      max_price: "0.05"             # USD per message cap
      validity_period: 3600         # seconds, 1–14400
routing:
  sms: twilio

Either from or messaging_service_sid is required (not both).

Create an API Key in the Twilio Console under Account → API Keys. Use Standard key type. The account_sid is your Account SID (starts with AC), api_key_sid is the Key SID (starts with SK), and api_key_secret is the secret shown once at creation time.

Environment-variable fallback

If providers.twilio is not declared, Norq registers Twilio when these env vars are set:

Var	Required
`NORQ_TWILIO_ACCOUNT_SID`	yes
`NORQ_TWILIO_API_KEY_SID`	yes
`NORQ_TWILIO_API_KEY_SECRET`	yes
`NORQ_TWILIO_FROM`	one of these two
`NORQ_TWILIO_MESSAGING_SERVICE_SID`	one of these two
`NORQ_TWILIO_STATUS_CALLBACK`	optional
`NORQ_TWILIO_MAX_PRICE`	optional
`NORQ_TWILIO_VALIDITY_PERIOD`	optional

Capabilities

Channels: SMS only.
Batching: none. Twilio’s API sends one message per request; the SDKs iterate recipients and call prepare_send per message.
MMS: not supported in v1 — Norq’s SMS template carries no media URLs.
CLI: works. Twilio uses HTTP Basic auth (ApiKeySid:ApiKeySecret), which the CLI executor handles natively. No OAuth2 or HTTP/2 required.

Request shape

Body: application/x-www-form-urlencoded (Twilio rejects JSON).
Auth: HTTP Basic with ApiKeySid:ApiKeySecret. The AccountSid appears only in the URL path.
Success: 200 or 201. Norq extracts the message SID from $.sid.
Retry: defaults — 429 + 5xx, 2 retries, 500ms backoff.