tracer-cloud--opensre/docs/messaging/twilio-sms.mdx

---
title: "Twilio SMS"
description: "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
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
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
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
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
{
  "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).