twilio

What this skill does

# twilio

## Purpose

Enable OpenClaw to operate Twilio “root” production workflows end-to-end: account and subaccount management, API keys and auth, console/billing/rate limits, and the operational patterns that sit on top (Messaging/Voice/Verify/SendGrid/Studio). This skill is for engineers who need to:

- Provision and rotate credentials safely (API Keys, Auth Tokens, SendGrid keys), including per-environment isolation.
- Debug and remediate production incidents (webhook failures, carrier errors, rate limits, invalid numbers, auth errors).
- Implement production-grade Messaging/Voice/Verify flows with correct compliance (STOP handling, 10DLC, toll-free verification).
- Control cost and performance (messaging services with geo-matching, concurrency, retry/backoff, recording/transcription costs).
- Automate Twilio operations via CLI + REST APIs + IaC patterns.

## Prerequisites

### Accounts and access

- Twilio account with Console access: https://console.twilio.com/
- For Messaging in US:
  - A2P 10DLC brand + campaign registration (required for most US long-code messaging).
  - Toll-free verification if using toll-free numbers for A2P.
  - Short code approval if using short codes.
- For WhatsApp:
  - WhatsApp Business Account (WABA) and Twilio WhatsApp sender configured.
- For Voice:
  - A Twilio phone number with Voice capability.
  - If using SIP trunking: Twilio Elastic SIP Trunking enabled.
- For Verify:
  - Verify service created (Verify V2).
- For SendGrid:
  - SendGrid account (can be separate from Twilio login), API key with appropriate scopes.

### Local tooling (exact versions)

- Node.js **20.11.1** (LTS) or **18.19.1** (LTS)
- Python **3.11.8** or **3.12.2**
- curl **8.5.0+**
- jq **1.7+**
- OpenSSL **3.0.13+** (for signature verification tooling)
- Docker **25.0.3+** (optional, for local webhook receivers and integration tests)

### Twilio SDKs (recommended pinned versions)

- Node: `twilio` **4.23.0**
- Python: `twilio` **9.0.5**
- SendGrid Node: `@sendgrid/mail` **8.1.1**
- SendGrid Python: `sendgrid` **6.11.0**

### Auth setup (Twilio)

Twilio supports:
- **Account SID** (starts with `AC...`)
- **Auth Token** (secret)
- **API Key SID** (starts with `SK...`) + **API Key Secret** (preferred over Auth Token for apps/CI)
- **Subaccounts** (each has its own Account SID/Auth Token; API Keys can be created per account)

Minimum recommended production posture:
- Use **API Key** + **Secret** in apps/CI.
- Keep **Auth Token** only for break-glass and console use; rotate if exposed.
- Separate **subaccounts** per environment (prod/stage/dev) and/or per tenant.

### Twilio CLI (optional but strongly recommended)

Twilio CLI is useful for interactive operations; for automation prefer REST + IaC, but CLI is still valuable for incident response.

- Twilio CLI: `twilio-cli` **5.17.0**
- Plugins:
  - `@twilio-labs/plugin-serverless` **3.0.2** (for Twilio Functions/Assets)
  - `@twilio-labs/plugin-flex` **6.0.6** (if using Flex)

Install via npm (see Installation & Setup).

## Core Concepts

### Accounts, subaccounts, projects

- **Account**: top-level billing entity. Identified by `AccountSid` (`AC...`).
- **Subaccount**: child account with its own credentials, numbers, messaging services, etc. Useful for environment isolation and tenant isolation.
- **Project**: Twilio Console UI grouping; not a separate security boundary. Don’t confuse with subaccounts.

Production pattern:
- One parent account for billing.
- Subaccounts per environment: `prod`, `staging`, `dev`.
- Optionally subaccounts per customer/tenant if you need strict isolation and separate phone number pools.

### Credentials

- **Auth Token**: master secret for an account. High blast radius.
- **API Keys**: scoped to an account; can be revoked without rotating Auth Token.
- **Key rotation**: create new key, deploy, verify, revoke old key.

### Messaging architecture

- **From** can be:
  - A phone number (10DLC long code, toll-free, short code)
  - A **Messaging Service SID** (`MG...`) which selects an appropriate sender (pooling, geo-match, sticky sender)
- **Status callbacks**: message lifecycle events via webhook:
  - `queued`, `sent`, `delivered`, `undelivered`, `failed` (and sometimes `read` for channels that support it, e.g., WhatsApp)
- **STOP handling**:
  - Twilio has built-in opt-out handling for many channels; you must not override it incorrectly.
  - Your app should treat STOP as a compliance event and suppress future sends to that recipient unless they opt back in (e.g., START).

### Voice architecture

- **TwiML**: XML instructions returned by your webhook to control calls.
  - `<Dial>`, `<Conference>`, `<Record>`, `<Say>` (with Polly voices), `<Gather>` for IVR.
- **Call status callbacks**: webhooks for call events.
- **Recording**: can be enabled per call or per conference; transcription is separate and has cost/latency.
- **SIP trunking**: connect PBX/SBC to Twilio; requires careful auth and IP ACLs.

### Verify V2

- Verify Service (`VA...`) defines channel configuration and policies.
- Verify checks are rate-limited and fraud-protected; you must handle `429` and Verify-specific error codes.
- Custom channels: email/push/TOTP can be integrated; treat as separate trust and deliverability domains.

### SendGrid

- Transactional vs marketing:
  - Transactional: API-driven, low latency, templated.
  - Marketing: campaigns, list management, compliance.
- Dynamic templates use Handlebars.
- Inbound Parse: webhook that turns inbound email into HTTP POST.

### Studio

- Studio Flows are state machines managed in Twilio.
- REST Trigger API can start a flow execution.
- Export/import flows for version control; A/B testing via Split widgets.

### Rate limits and retries

- Twilio enforces per-account and per-resource rate limits; you will see `20429` and HTTP `429`.
- Webhooks are retried by Twilio on non-2xx responses; your endpoints must be idempotent.

## Installation & Setup

### Official Python SDK

**Repository:** https://github.com/twilio/twilio-python  
**PyPI:** https://pypi.org/project/twilio/ · **Supported:** Python 3.7–3.13

```shell
pip install twilio
```

```python
from twilio.rest import Client
import os

# Environment variables (recommended)
client = Client()  # reads TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN

# API Key auth (preferred for production)
client = Client(
    os.environ["TWILIO_API_KEY"],
    os.environ["TWILIO_API_SECRET"],
    os.environ["TWILIO_ACCOUNT_SID"]
)

# Regional edge routing
client = Client(region='au1', edge='sydney')
```

Source: [twilio/twilio-python — client auth](https://github.com/twilio/twilio-python/blob/main/README.md#api-credentials)

### Ubuntu 22.04 / 24.04 (x86_64)

Install dependencies:

```bash
sudo apt-get update
sudo apt-get install -y curl jq ca-certificates gnupg lsb-release openssl
```

Node.js 20.11.1 via NodeSource:

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v  # expect v20.11.x
npm -v
```

Twilio CLI 5.17.0:

```bash
sudo npm install -g [email protected]
twilio --version
```

Optional plugins:

```bash
twilio plugins:install @twilio-labs/[email protected]
twilio plugins:install @twilio-labs/[email protected]
twilio plugins
```

Python 3.11 (if needed):

```bash
sudo apt-get install -y python3 python3-venv python3-pip
python3 --version
```

### Fedora 39 / 40 (x86_64)

```bash
sudo dnf install -y curl jq openssl nodejs npm python3 python3-pip
node -v
sudo npm install -g [email protected]
twilio --version
```

### macOS 14 (Sonoma) Intel

Homebrew:

```bash
brew update
brew install node@20 jq openssl@3 [email protected]
brew link --force --overwrite node@20
node -v
```

Twilio CLI:

```bash
npm install -g [email protected]
twilio --version
```

### macOS 14 (Sonoma) Apple Silicon (ARM64)

Same as Intel; ensure correct PATH:

```bash
brew install node@20 jq openssl@3 [email protected]
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
sou