twilio-account-setup

What this skill does

## 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 |
|