Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt

Use this file to discover all available pages before exploring further.

Connect your existing Twilio numbers for inbound and outbound use-cases — including international numbers.

​
Prerequisites

​
Setup

A dedicated subaccount makes it easy to manage numbers and credentials imported to Cartesia within your broader Twilio setup.
  1. Open the Twilio Console
  2. Go to Account → Subaccounts → Create new Subaccount
  3. Name it (e.g., cartesia-production)
  4. Copy the Account SID
You can also use your main Twilio account directly. Subaccounts are recommended but not required.

​
Step 2: Create an API Key

Create a Standard API key in your Twilio subaccount. API keys are preferred over auth tokens because they can be rotated independently.
  1. In your subaccount, go to Account → API keys & tokens or visit the console here
  2. Click Create API Key → choose Standard
  3. Save the SID and Secret in a password manager
Copy and store the API key secret immediately. Twilio only shows it once. If you lose it, create a new key.
If you plan to import phone numbers from multiple regions, create a separate API key for each region. See Regional Routing.

​
Step 3: Connect Your Twilio Account

Add your Twilio credentials to your Cartesia account. They will be validated against Twilio before saving.
  1. Go to Phone Numbers → click Add Number → Import from Twilio
  2. Select Link new account
  3. Enter your Account SID, API Key SID, API Key Secret, and region
Linking a Twilio account in Playground

​
Step 4: Import a Phone Number

Import a number you already own in your Twilio account.
  1. In the same Import from Twilio panel, enter your phone number with country code (e.g., +14155551234)
  2. Give it a name
  3. Optionally assign an agent — you can do this later too!
The phone number must already exist in your Twilio account. Cartesia does not purchase numbers on your behalf.

​
Step 5: Assign to an Agent

Assign a number to an agent so inbound calls are routed to it. You can assign multiple numbers to the same agent.
  1. Click on a phone number to open its detail page
  2. In the Agent card, search for and select your agent
Assigning an agent to a phone number

​
Inbound Calls

When someone calls your Twilio number, they’re connected to the assigned Cartesia agent.
You may assign multiple numbers to the same agent for different regions or use-cases — for example, a US support line and a UK support line both handled by one agent.

​
Outbound Calls

Your agent can initiate calls to any phone number, including international ones at standard Twilio rates.
Trigger outbound calls from the agent’s page or via the CLI:
cartesia call <phone_number> <agent_id>
Outbound calls use the credentials tied to the phone number’s provider. A us1 provider routes through the US Twilio edge; an ie1 provider routes through Ireland. See Regional Routing for details.

​
Credential Rotation

Rotate your Twilio API key without downtime:
  1. Create a new API key in Twilio (Step 2 above)
  2. Update the provider in Cartesia:
Go to Phone Numbers → Settings and update the credentials for your Twilio account.
Cartesia validates the new credentials and checks that all phone numbers on the provider are reachable before applying the update.
  1. Revoke the old key in the Twilio console

​
Removing a Number

You must unassign an imported phone number before deleting it. Deleting a Twilio number from Cartesia does not remove it from your Twilio account. The number remains available in Twilio for other use.

​
What’s Next