Skip to main content
OpenSRE’s Twilio integration delivers investigation findings via SMS using the Twilio Messaging API. It is configured independently of the existing whatsapp integration, though both can share the same Twilio account credentials.
WhatsApp delivery is owned entirely by the separate whatsapp integration (opensre integrations setup whatsapp) — see the WhatsApp page. The twilio integration documented here is SMS-only. For voice paging on critical incidents, route through PagerDuty or Opsgenie, which provide voice escalation with proper acknowledgement.

​
Prerequisites

  • A Twilio account: Sign up.
  • A Twilio-provisioned phone number or a Messaging Service SID.

​
Step 1: Configure the integration

opensre integrations setup twilio
You’ll be prompted for:
  • Twilio Account SID (starts with AC...)
  • Twilio Auth Token
  • Twilio SMS From number (E.164, e.g. +14155551234) — or leave blank and provide a Messaging Service SID (starts with MG...)
  • optional default recipient

​
Via environment variables

Add to your .env file: 
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=your_auth_token

# Set either TWILIO_SMS_FROM or TWILIO_SMS_MESSAGING_SERVICE_SID
TWILIO_SMS_FROM=+14155551234
TWILIO_SMS_MESSAGING_SERVICE_SID=
TWILIO_SMS_DEFAULT_TO=+1234567890
The twilio env-bootstrap activates when the account + token are set and an SMS sender (TWILIO_SMS_FROM or TWILIO_SMS_MESSAGING_SERVICE_SID) is present. The legacy whatsapp record is bootstrapped independently from TWILIO_WHATSAPP_FROM.

​
Step 2: Verify

opensre integrations verify twilio
A passing verification confirms:
  • The Twilio account credentials authenticate against the Twilio Account API.
  • The SMS channel is enabled and has a usable sender (from_number or messaging_service_sid).
Sample passing output: 
twilio: passed — Connected to Twilio account My Company; SMS channel ready.
If the account authenticates but the SMS channel has no sender, verification returns failed with a message telling you to set a from_number or messaging_service_sid.

​
Step 3: Test with an investigation

Trigger a real investigation against a bundled fixture: 
opensre investigate --input tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json
When the investigation finishes, the RCA summary is truncated to the SMS body limit (1600 chars) and posted via the Twilio Messaging API to the configured recipient.

​
Programmatic notifications: twilio_notify tool

When the Twilio integration is configured, the investigation planner exposes a twilio_notify tool. The tool sends a short notification body via SMS and returns the Twilio Message SID for traceability. 
{
  "name": "twilio_notify",
  "arguments": {
    "to": "+14155550000",
    "body": "DB CPU > 95% — paging on-call"
  }
}

​
Troubleshooting

​
opensre integrations verify twilio errors

DetailLikely cause
Missing account_sidTWILIO_ACCOUNT_SID is unset.
Missing auth_tokenTWILIO_AUTH_TOKEN is unset.
Twilio API check failed: 401The SID/token pair is invalid.
SMS channel is not readyNo SMS sender — set TWILIO_SMS_FROM or TWILIO_SMS_MESSAGING_SERVICE_SID.

​
SMS never arrives but verify passes

  • Confirm TWILIO_SMS_FROM (or the Messaging Service SID) is provisioned for the destination country.
  • Confirm the recipient is in E.164 format (+14155550000).
  • For trial accounts: the recipient must be a verified caller ID.
  • Inspect Messages in the Twilio Console for an error code; common failures (30007, 21610, etc.) are documented at twilio.com/docs/api/errors.