既存の Twilio 番号を、国際番号を含むインバウンド／アウトバウンドのユースケース向けに接続します。
前提条件
セットアップ
ステップ 1: Twilio サブアカウントを作成（推奨）
専用のサブアカウントを使うと、Cartesia にインポートする番号や認証情報を、より広範な Twilio セットアップの中で簡単に管理できます。
- Twilio コンソール を開きます
- Account → Subaccounts → Create new Subaccount に移動します
- 名前を付けます（例：
cartesia-production）
- Account SID をコピーします
メインの Twilio アカウントをそのまま使うこともできます。サブアカウントは推奨ですが必須ではありません。
ステップ 2: API キーを作成
Twilio サブアカウント内で標準 API キーを作成します。auth トークンよりも API キーを推奨します。独立してローテーションできるためです。
- サブアカウントで Account → API keys & tokens に移動するか、ここ からコンソールにアクセスします
- Create API Key をクリックして Standard を選択します
- SID と Secret をパスワードマネージャーに保存します
API キーシークレットはその場で必ずコピーして保存してください。Twilio はシークレットを 1 回しか表示しません。紛失した場合は新しいキーを作成してください。
ステップ 3: Twilio アカウントを接続
Twilio の認証情報を Cartesia アカウントに追加します。保存前に Twilio に対して検証されます。
- Phone Numbers に移動 → Add Number → Import from Twilio をクリック
- Link new account を選択
- Account SID、API Key SID、API Key Secret、リージョンを入力
curl -X POST "https://api.cartesia.ai/agents/phone-numbers/providers" \
-H "Authorization: Bearer $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Cartesia-Version: 2025-04-16" \
-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"
}'
ステップ 4: 電話番号をインポート
Twilio アカウントですでに所有している番号をインポートします。
- 同じ Import from Twilio パネルで、国コード付きの電話番号を入力します（例：
+14155551234）
- 名前を付けます
- 必要に応じてエージェントを割り当てます。これは後からでも設定できます！
curl -X POST "https://api.cartesia.ai/agents/phone-numbers" \
-H "Authorization: Bearer $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Cartesia-Version: 2025-04-16" \
-d '{
"label": "Support Line",
"number": "+14155551234",
"provider": { "id": "YOUR_PROVIDER_ID" }
}'
電話番号は Twilio アカウントにすでに存在している必要があります。Cartesia があなたに代わって番号を購入することはありません。
ステップ 5: エージェントに割り当て
電話番号をエージェントに割り当てて、インバウンド通話がそのエージェントにルーティングされるようにします。同じエージェントに複数の番号を割り当てることもできます。
- 電話番号をクリックして詳細ページを開きます
- Agent カードでエージェントを検索して選択します
cartesia phone-numbers assign <phone-number-id> --agent-id <agent-id>
cartesia phone-numbers unassign <phone-number-id>
cartesia phone-numbers ls --type twilio
curl -X PATCH "https://api.cartesia.ai/agents/phone-numbers/YOUR_PHONE_NUMBER_ID" \
-H "Authorization: Bearer $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Cartesia-Version: 2025-04-16" \
-d '{
"agent_id": "YOUR_AGENT_ID"
}'
agent_id を null に設定します。インバウンド通話
誰かがあなたの Twilio 番号に発信すると、割り当てられた Cartesia エージェントに接続されます。
リージョンやユースケースごとに複数の番号を同じエージェントに割り当てることができます。たとえば、米国のサポートラインと英国のサポートラインの両方を 1 つのエージェントで処理することも可能です。
アウトバウンド通話
エージェントは、Twilio の標準料金で国際番号を含む任意の電話番号に通話を発信できます。
エージェントページまたは CLI からアウトバウンド通話をトリガーします：cartesia call <phone_number> <agent_id>
curl -X POST "https://api.cartesia.ai/twilio/call/outbound" \
-H "Authorization: Bearer $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Cartesia-Version: 2025-04-16" \
-d '{
"target_numbers": ["+442012345678"],
"agent_id": "YOUR_AGENT_ID"
}'
us1 プロバイダーは米国の Twilio エッジ経由でルーティングされ、ie1 プロバイダーはアイルランド経由でルーティングされます。詳細は リージョナルルーティング を参照してください。
認証情報のローテーション
ダウンタイムなしで Twilio API キーをローテーションします：
- Twilio で新しい API キーを作成します（上記のステップ 2）
- Cartesia のプロバイダーを更新します：
Phone Numbers → Settings に移動し、Twilio アカウントの認証情報を更新します。
curl -X PATCH "https://api.cartesia.ai/agents/phone-numbers/providers/YOUR_PROVIDER_ID" \
-H "Authorization: Bearer $CARTESIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Cartesia-Version: 2025-04-16" \
-d '{
"type": "twilio",
"api_key_sid": "NEW_API_KEY_SID",
"api_key_secret": "NEW_API_KEY_SECRET",
"region": "us1"
}'
- Twilio コンソールで古いキーを失効させます
番号の削除
インポートした電話番号は、削除する前に必ず割り当てを解除する必要があります。Cartesia から Twilio 番号を削除しても、Twilio アカウントからは削除されません。番号はそのまま Twilio で他の用途に利用できます。
次のステップ
