X Openai Twilio Account Setup 64319f9

---
name: x-openai-twilio-account-setup-64319f9
description: Create and configure a Twilio account from scratch. Covers free trial signup, trial limitations, getting credentials (Account SID and Auth Token), buying a phone number, verifying recipient numbers for trial use, SDK installation, first API call, subaccount management (creation, inheritance, credential isolation, limits), and enabling specific products (AI Assistants, Conversations, Verify, ConversationRelay, WhatsApp). Use this skill before any other Twilio skill if you do not yet have a Twilio account or need to enable a product. For Organization-level governance (SSO, SCIM, multi-team), see `twilio-organizations-setup`.
---

### 导出副本边界与技能别名

迁移、安装、修复和经验回写只作用于当前加载的目标宿主技能副本。原 Codex 技能/MCP、下载的源码和 `original-skills` 均为来源材料，不因执行本副本而写入；只有用户另行明确要求配置 Codex 产品本身时，才按该产品流程处理指定目标。脚本需要安装目录或状态目录时，显式提供目标路径；不得从 `CODEX_HOME` 隐式推断写入位置。

跨技能名称可能沿用源库别名。先查 [技能别名表](../../skill-aliases.json)，优先选择同来源、同插件的条目，再使用其 `id` 调用或读取对应入口；不得假定旧 `$skill`、`superpowers:skill` 名称在新宿主直接注册。不能确定目标时先核对，不替换真实产品命令或 Shell 环境变量。

## 跨宿主使用约定

本副本供支持 Agent Skills 的客户端使用。先检查当前宿主实际提供的工具、权限和已连接服务，再执行正文工作流。原文中的宿主工具标识是能力参考；只有实际发现该工具时才可调用，其他宿主应使用经核验的等价 MCP、CLI 或 API。没有等价能力的步骤必须报告不可用，不能虚构调用或完成状态。

技能资源以本技能目录为基准；输出写入当前项目中用户指定的位置。通过技能名称或自然语言触发，具体快捷命令由宿主决定。涉及真实产品、模型 API、协议字段和官方网址的名称保持原意。授权、审批、隐私和工具范围限制在迁移后仍然有效；不得为兼容而扩大权限。具体依赖与迁移说明见同目录 `PORTABILITY.md`。

## Overview

Every Twilio skill requires an active Twilio account and credentials. This skill covers the one-time setup steps that are prerequisites for all other Twilio skills.

---

## Quickstart

1. Sign up at [twilio.com/try-twilio](https://www.twilio.com/try-twilio) -- enter name, email, password
2. Verify your email and personal phone number
3. Get your credentials from [Console > Account > API keys & tokens](https://console.twilio.com/us1/account/keys-credentials/api-keys):

```bash
export TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export TWILIO_AUTH_TOKEN=your_auth_token
```

4. Buy a phone number at [Console > Phone Numbers > Buy a number](https://console.twilio.com/us1/develop/phone-numbers/search)

5. Install the SDK and send your first message:

**Python**
```bash
pip install twilio
```
```python
import os
from twilio.rest import Client

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
message = client.messages.create(
    to="+15558675310",  # must be verified on trial accounts
    from_="+15017122661",  # your Twilio number
    body="Hello from Twilio!"
)
print(f"Sent: {message.sid}")
```

**Node.js**
```bash
npm install twilio
```
```node
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);

const message = await client.messages.create({
    to: "+15558675310",  // must be verified on trial accounts
    from: "+15017122661",  // your Twilio number
    body: "Hello from Twilio!",
});
console.log(`Sent: ${message.sid}`);
```

You're ready to use any Twilio skill. Trial accounts have restrictions -- see Constraints below.

---

## Key Patterns

### Verify Recipient Numbers (trial accounts only)

Trial accounts can only send to **verified phone numbers** (up to 5 per account).

1. Go to [Console > Phone Numbers > Verified Caller IDs](https://console.twilio.com/us1/develop/phone-numbers/verified-caller-ids)
2. Click **Add a new Caller ID** and verify via SMS code

Verified numbers work across both messaging and voice. Remove this restriction by upgrading your account.

### Enable Specific Products

Some products require explicit activation:

| Product | How to enable |
|---------|--------------|
| AI Assistants | [Console > Explore Products > AI Assistants](https://console.twilio.com/us1/develop/ai-assistants) > **Get started** |
| Conversations | [Console > Conversations > Manage > Overview](https://console.twilio.com/us1/develop/conversations/manage/overview) > **Enable Conversations** |
| Verify | [Console > Verify > Services](https://console.twilio.com/us1/verify/services) > **Create new** |
| WhatsApp (sandbox) | [Console > Messaging > Try it out > Send a WhatsApp message](https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn) |
| ConversationRelay | [Console > Voice > ConversationRelay](https://console.twilio.com/us1/voice/conversation-relay) > complete onboarding form |

### SDK Installation

| Language | Install | SDK package |
|----------|---------|-------------|
| Python | `pip install twilio` | `twilio` |
| Node.js | `npm install twilio` | `twilio` |
| Java | Maven/Gradle | `com.twilio.sdk:twilio` |
| C# | `dotnet add package Twilio` | `Twilio` |
| Ruby | `gem install twilio-ruby` | `twilio-ruby` |
| PHP | `composer require twilio/sdk` | `twilio/sdk` |
| Go | `go get github.com/twilio/twilio-go` | `twilio-go` |

### Initialize the Client

Always load credentials from environment variables -- never hardcode them.

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

client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
```

**Node.js**
```node
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
```

For production, use API Keys instead of Auth Token. See `twilio-iam-auth-setup`.

### Twilio CLI Setup

The CLI is useful for quick operations and local webhook testing.

```bash
# Install (macOS)
brew tap twilio/brew && brew install twilio

# Install (npm -- all platforms)
npm install -g twilio-cli

# Login (creates an API key automatically)
twilio login

# Verify setup
twilio phone-numbers:list
```

The CLI stores profiles for switching between accounts:
```bash
# List profiles
twilio profiles:list

# Switch active profile
twilio profiles:use my-project

# Use environment variables instead of profiles
export TWILIO_ACCOUNT_SID=ACxxxxxxxx
export TWILIO_AUTH_TOKEN=xxxxxxxx
```

Precedence: `--profile` flag > environment variables > active profile.

### Accounts and Subaccounts

**Creating a new Twilio account:** Accounts can only be created from the Console UI — there is no API for creating top-level accounts. A new account is automatically created when a user signs up. Additional accounts can be created from Console > My Accounts (or "View all accounts").

**To see all your accounts:** Console > My Accounts shows all accounts and subaccounts you have access to. For Organization-wide visibility, see Console > Admin > Accounts (requires Organization admin role). See `twilio-organizations-setup` for Organization-level governance.

### Subaccounts

Subaccounts are child accounts under your main (parent) account. Use them for multi-tenant apps, per-customer isolation, or team separation.

**How they differ from the parent account:**
- Resources (numbers, calls, messages) are **isolated** — a subaccount cannot see the parent's resources or other subaccounts' resources
- Billing is **consolidated** to the parent — a single Twilio balance for all subaccounts
- Voice and SMS permissions **inherit** from the parent
- Phone numbers can be transferred between parent and subaccounts

**Create via Console:** Console > My Accounts > Create Subaccount

**Create via API:**

**Python**
```python
subaccount = client.api.accounts.create(friendly_name="Customer A")
print(f"Subaccount SID: {subaccount.sid}")
# Store securely — auth_token is only shown at creation time
# e.g., secrets_manager.store("subaccount_auth_token", subaccount.auth_token)
```

**Node.js**
```javascript
const subaccount = await client.api.accounts.create({ friendlyName: "Customer A" });
console.log(`Subaccount SID: ${subaccount.sid}`);
```

### Subaccount Credential Isolation

**Always use the subaccount's own credentials** (API Keys or Auth Token) when accessing subaccount resources — do NOT use the parent account's credentials as a shortcut.

**Python — access subaccount resources**
```python
# Correct: use subaccount credentials
sub_client = Client(subaccount.sid, subaccount.auth_token)
call = sub_client.calls.create(
    to="+15558675310",
    from_="+15017122661",  # number owned by this subaccount
    url="https://yourapp.com/voice"
)

# Also correct: parent credentials with subaccount SID (v2010 API only)
parent_client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
calls = parent_client.api.accounts(subaccount.sid).calls.list()
```

**Critical:** Resources on separate subdomains (`studio.twilio.com`, `taskrouter.twilio.com`) **require subaccount-specific credentials**. Parent account credentials will not work on these subdomains.

### Subaccount Limits

- **Default limit:** 1,000 subaccounts per parent account
- **Trial accounts:** Can create only 1 subaccount — upgrade to create more
- **At the limit:** Contact Twilio Support with your use case to request an increase
- **Closing:** Set status to `closed` via API or Console. Closed subaccounts are automatically deleted after 30 days
- **Suspension cascade:** Suspending the parent account automatically suspends ALL subaccounts

### Upgrade from Trial

1. Click **Upgrade** at the top of the Console, or go to [Console > Admin > Account billing](https://console.twilio.com/us1/admin/billing)
2. Provide name, address, and payment details
3. Your trial phone number carries over; trial balance does not

---

## Trial Restrictions at a Glance

| Feature | Trial | Upgraded |
|---------|-------|----------|
| Phone numbers | 1 | Unlimited |
| Send to unverified numbers | No | Yes |
| Outbound message prefix | Yes (visible to recipient) | No |
| Verified caller IDs | Up to 5 | Not needed |
| A2P 10DLC registration | No | Yes |
| Daily WhatsApp messages | 50 | Unlimited |
| ConversationRelay | No | Yes (after onboarding) |
| Voice: outbound calls | Domestic only | International |

---

## CANNOT

- **Cannot create top-level accounts via API** — Only Console UI. A new account is created at signup; additional accounts from Console > My Accounts.
- **Cannot create more than 1 subaccount on trial** — Upgrade your account first, then you can create up to 1,000.
- **Cannot access subdomain resources with parent credentials** — Studio, TaskRouter, and other subdomain APIs require subaccount-specific credentials. Parent credentials return auth errors.
- **Cannot undo a closed subaccount after 30 days** — Closed subaccounts are permanently deleted. Suspension is reversible; closure is not.
- **Cannot transfer trial balance to a paid account** — Trial credits are forfeited on upgrade.
- **Cannot send to unverified numbers on trial** — Only verified Caller IDs (up to 5) can receive messages or calls.
- **Auth Token rotation invalidates ALL API keys** — This is a one-way door. Use API Keys from day one. See `twilio-security-api-auth`.
- **API Key secrets shown only once at creation** — Store them immediately. Cannot be retrieved afterward.
- **AI Assistants and ConversationRelay require approval** — Limited access products. Activation is not instant.

---

## Next Steps

- **Organization governance (SSO, SCIM, multi-team):** `twilio-organizations-setup`
- **Secure credential management and API Keys:** `twilio-security-api-auth`
- **Send your first SMS:** `twilio-sms-send-message`
- **Send your first WhatsApp message:** `twilio-whatsapp-send-message`
- **Receive incoming messages:** `twilio-messaging-webhooks`
- **US SMS compliance (A2P 10DLC):** `twilio-compliance-onboarding`
- **Webhook setup:** `twilio-webhook-architecture`