Twilio integration - Cartesia Docs

Connect your Twilio account to use your existing numbers, including international numbers, for inbound and outbound calls.

Prerequisites

A Twilio account with at least one phone number
A Cartesia account with an API key

Set up

Step 1: Create a Twilio subaccount (recommended)

A dedicated subaccount keeps the numbers and credentials you share with Cartesia separate from the rest of your Twilio setup.

Open the Twilio Console.
Go to Account → Subaccounts → Create new Subaccount.
Name it, for example cartesia-production.
Copy the Account SID.

You can also use your main Twilio account. Subaccounts are recommended but not required.

Step 2: Create an API key

Create a Standard API key in your subaccount. API keys can be rotated independently, which auth tokens cannot.

In your subaccount, go to Account → API keys & tokens, or open the create page directly.
Click Create API Key and choose Standard.
Save the SID and Secret in a password manager.

Twilio shows the API key secret once. If you lose it, create a new key.

If you import numbers from more than one Twilio region, create a separate API key for each region. See Regional routing.

Step 3: Connect your Twilio account

Cartesia validates the credentials against Twilio before saving them.

Playground
API

Go to Phone Numbers, click Add Number, then Import from Twilio.
Select Link new account.
Enter your Account SID, API Key SID, API Key Secret, and region.

Linking a Twilio account in the Playground — Import from Twilio panel with Link new account fields

curl -X POST "https://api.cartesia.ai/agents/phone-numbers/providers" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "twilio",
    "account_sid": "YOUR_TWILIO_ACCOUNT_SID",
    "api_key_sid": "YOUR_API_KEY_SID",
    "api_key_secret": "YOUR_API_KEY_SECRET",
    "region": "us1"
  }'

Step 4: Import a phone number

The number must already exist in your Twilio account. Cartesia does not purchase numbers on your behalf.

Playground
API

In the Import from Twilio panel, enter the phone number with its country code, for example +14155551234.
Give it a name.
Optionally assign an agent. You can also do this later.

curl -X POST "https://api.cartesia.ai/agents/phone-numbers" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Support line",
    "number": "+14155551234",
    "provider": { "id": "YOUR_PROVIDER_ID" }
  }'

Step 5: Assign an agent

Inbound calls on the number are routed to the agent you assign. Assign it from the number’s detail page in the Playground or through the Phone Numbers API. One agent can handle several numbers, for example a US line and a UK line.

Assigning an agent to a phone number — Phone number detail page with agent assignment

Outbound calls

Your agent can call any phone number, including international numbers at your Twilio rates. Use the imported number as from_number_id when you place an outbound call. Outbound calls use the credentials of the number’s provider. A us1 provider routes through Twilio’s US edge, and an ie1 provider routes through Ireland. See Regional routing.

Rotate credentials

Rotate your Twilio API key without downtime:

Create a new API key in Twilio, as in Step 2.
Update the provider in Cartesia. Cartesia validates the credentials and verifies each number assigned to an agent before saving.
Revoke the old key in the Twilio console.

Playground
API

Go to Phone Numbers → Settings.
Under Twilio Accounts, click the edit button for the provider.
Enter the new API Key SID and secret, then click Update credentials.

The Account SID and region cannot be changed in the Playground.

curl -X PATCH "https://api.cartesia.ai/agents/phone-numbers/providers/YOUR_PROVIDER_ID" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "twilio",
    "api_key_sid": "NEW_API_KEY_SID",
    "api_key_secret": "NEW_API_KEY_SECRET"
  }'

If validation fails, the stored credentials remain unchanged and the error lists unreachable numbers assigned to agents.

Recover after revoking a key

If you already revoked the stored key, create a replacement under the same Twilio Account SID. Delete from Cartesia any numbers already released from Twilio, then update the provider:

Open the released number in Phone Numbers.
Click Delete. You do not need to unassign its agent first.
Repeat for each released number, then update the provider credentials.

If the update reports other unreachable numbers, verify them in Twilio. Delete only numbers you released, then retry.

Remove a number

You can delete a Twilio number while it is assigned. Cartesia disconnects the agent and attempts to clear the Twilio webhook. Revoked credentials or a number already released from Twilio do not block deletion from Cartesia. Deleting from Cartesia does not release the number from Twilio. Release it separately in Twilio if needed.

Remove a Twilio account

Go to Phone Numbers → Settings and delete the provider. Cartesia blocks deletion until you delete all linked numbers.

​Prerequisites

​Set up

​Step 1: Create a Twilio subaccount (recommended)

​Step 2: Create an API key

​Step 3: Connect your Twilio account

​Step 4: Import a phone number

​Step 5: Assign an agent

​Outbound calls

​Rotate credentials

​Recover after revoking a key

​Remove a number

​Remove a Twilio account

Prerequisites

Set up

Step 1: Create a Twilio subaccount (recommended)

Step 2: Create an API key

Step 3: Connect your Twilio account

Step 4: Import a phone number

Step 5: Assign an agent

Outbound calls

Rotate credentials

Recover after revoking a key

Remove a number

Remove a Twilio account