> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio SMS

> Deliver investigation findings via Twilio SMS as a standalone, independently configurable channel.

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.

<Note>
  WhatsApp delivery is owned entirely by the separate `whatsapp` integration
  (`opensre integrations setup whatsapp`) — see the [WhatsApp](/messaging/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.
</Note>

***

## Prerequisites

* A Twilio account: [Sign up](https://www.twilio.com/try-twilio).
* A Twilio-provisioned phone number **or** a Messaging Service SID.

***

## Step 1: Configure the integration

### Via CLI wizard (recommended)

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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.

```json theme={null}
{
  "name": "twilio_notify",
  "arguments": {
    "to": "+14155550000",
    "body": "DB CPU > 95% — paging on-call"
  }
}
```

***

## Troubleshooting

### `opensre integrations verify twilio` errors

| Detail                         | Likely cause                                                                 |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `Missing account_sid`          | `TWILIO_ACCOUNT_SID` is unset.                                               |
| `Missing auth_token`           | `TWILIO_AUTH_TOKEN` is unset.                                                |
| `Twilio API check failed: 401` | The SID/token pair is invalid.                                               |
| `SMS channel is not ready`     | No 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](https://www.twilio.com/docs/api/errors).