Twilio インテグレーション

既存の Twilio 番号を、国際番号を含むインバウンド／アウトバウンドのユースケース向けに接続します。

前提条件

少なくとも 1 つの電話番号を持つ Twilio アカウント
API キーを持つ Cartesia アカウント

セットアップ

ステップ 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 回しか表示しません。紛失した場合は新しいキーを作成してください。

複数のリージョンから電話番号をインポートする予定がある場合は、リージョンごとに別の API キーを作成してください。リージョナルルーティングを参照してください。

ステップ 3: Twilio アカウントを接続

Twilio の認証情報を Cartesia アカウントに追加します。保存前に Twilio に対して検証されます。

Playground
API

Phone Numbers に移動 → Add Number → Import from Twilio をクリック
Link new account を選択
Account SID、API Key SID、API Key Secret、リージョンを入力

プレイグラウンドでの Twilio アカウントのリンク — 新規アカウントのリンクフィールドを持つ Twilio インポートパネル

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 アカウントですでに所有している番号をインポートします。

Playground
API

同じ 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: エージェントに割り当て

電話番号をエージェントに割り当てて、インバウンド通話がそのエージェントにルーティングされるようにします。同じエージェントに複数の番号を割り当てることもできます。

Playground
CLI
API

電話番号をクリックして詳細ページを開きます
Agent カードでエージェントを検索して選択します

電話番号にエージェントを割り当てる — エージェント割り当てを伴う電話番号の詳細ページ

cartesia phone-numbers assign <phone-number-id> --agent-id <agent-id>

割り当てを解除するには：

cartesia phone-numbers unassign <phone-number-id>

電話番号 ID を確認するために Twilio 番号を一覧表示します：

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 の標準料金で国際番号を含む任意の電話番号に通話を発信できます。

Playground
API

エージェントページまたは 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 のプロバイダーを更新します：

Playground
API

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"
  }'

\u0001\u0001\u0001 Cartesia は新しい認証情報を検証し、プロバイダーのすべての電話番号に到達可能であることを確認してから更新を適用します。

Twilio コンソールで古いキーを失効させます

番号の削除

インポートした電話番号は、削除する前に必ず割り当てを解除する必要があります。Cartesia から Twilio 番号を削除しても、Twilio アカウントからは削除されません。番号はそのまま Twilio で他の用途に利用できます。

次のステップ

最初のアウトバウンド通話を発信する
マルチリージョンデプロイメント用にリージョナルルーティングを設定する
Phone Numbers API および Providers API を確認する

はじめに

オーディオ連携

デプロイとモニタリング

評価

開発者ツール

Twilio インテグレーション

前提条件

セットアップ

ステップ 1: Twilio サブアカウントを作成（推奨）

ステップ 2: API キーを作成

ステップ 3: Twilio アカウントを接続

ステップ 4: 電話番号をインポート

ステップ 5: エージェントに割り当て

インバウンド通話

アウトバウンド通話

認証情報のローテーション

番号の削除

次のステップ

​前提条件

​セットアップ

​ステップ 1: Twilio サブアカウントを作成（推奨）

​ステップ 2: API キーを作成

​ステップ 3: Twilio アカウントを接続

​ステップ 4: 電話番号をインポート

​ステップ 5: エージェントに割り当て

​インバウンド通話

​アウトバウンド通話

​認証情報のローテーション

​番号の削除

​次のステップ

前提条件

セットアップ

ステップ 1: Twilio サブアカウントを作成（推奨）

ステップ 2: API キーを作成

ステップ 3: Twilio アカウントを接続

ステップ 4: 電話番号をインポート

ステップ 5: エージェントに割り当て

インバウンド通話

アウトバウンド通話

認証情報のローテーション

番号の削除

次のステップ