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

# Twilio インテグレーション

> 既存の Twilio アカウントを接続し、既存の電話番号をインポートします。

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

## 前提条件

* 少なくとも 1 つの電話番号を持つ [Twilio アカウント](https://www.twilio.com/try-twilio)
* API キーを持つ [Cartesia アカウント](https://play.cartesia.ai)

## セットアップ

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

専用のサブアカウントを使うと、Cartesia にインポートする番号や認証情報を、より広範な Twilio セットアップの中で簡単に管理できます。

1. [Twilio コンソール](https://console.twilio.com) を開きます
2. **Account** → **Subaccounts** → **Create new Subaccount** に移動します
3. 名前を付けます（例：`cartesia-production`）
4. **Account SID** をコピーします

<Tip>
  メインの Twilio アカウントをそのまま使うこともできます。サブアカウントは推奨ですが必須ではありません。
</Tip>

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

Twilio サブアカウント内で標準 API キーを作成します。auth トークンよりも API キーを推奨します。独立してローテーションできるためです。

1. サブアカウントで **Account** → **API keys & tokens** に移動するか、[ここ](https://console.twilio.com/us1/account/keys-credentials/api-keys/create) からコンソールにアクセスします
2. **Create API Key** をクリックして **Standard** を選択します
3. **SID** と **Secret** をパスワードマネージャーに保存します

<Warning>
  API キーシークレットはその場で必ずコピーして保存してください。Twilio はシークレットを 1 回しか表示しません。紛失した場合は新しいキーを作成してください。
</Warning>

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

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

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

<Tabs>
  <Tab title="Playground">
    1. **Phone Numbers** に移動 → **Add Number** → **Import from Twilio** をクリック
    2. **Link new account** を選択
    3. Account SID、API Key SID、API Key Secret、リージョンを入力

    <Frame caption="新規アカウントのリンクフィールドを持つ Twilio インポートパネル">
      <img src="https://mintcdn.com/cartesia-2650f86a/cyPOLB5BGhebR1Zv/assets/images/agents/telephony/import-from-twilio.png?fit=max&auto=format&n=cyPOLB5BGhebR1Zv&q=85&s=dec025eb32889c5ed3f30473316974f2" alt="プレイグラウンドでの Twilio アカウントのリンク" width="2872" height="1914" data-path="assets/images/agents/telephony/import-from-twilio.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

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

Twilio アカウントですでに所有している番号をインポートします。

<Tabs>
  <Tab title="Playground">
    1. 同じ **Import from Twilio** パネルで、国コード付きの電話番号を入力します（例：`+14155551234`）
    2. 名前を付けます
    3. 必要に応じてエージェントを割り当てます。これは後からでも設定できます！
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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" }
      }'
    ```
  </Tab>
</Tabs>

<Note>
  電話番号は Twilio アカウントにすでに存在している必要があります。Cartesia があなたに代わって番号を購入することはありません。
</Note>

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

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

<Tabs>
  <Tab title="Playground">
    1. 電話番号をクリックして詳細ページを開きます
    2. **Agent** カードでエージェントを検索して選択します

    <Frame caption="エージェント割り当てを伴う電話番号の詳細ページ">
      <img src="https://mintcdn.com/cartesia-2650f86a/cyPOLB5BGhebR1Zv/assets/images/agents/telephony/phone-number-details.png?fit=max&auto=format&n=cyPOLB5BGhebR1Zv&q=85&s=f05407f657941a7a6c9cbda1a8dee44e" alt="電話番号にエージェントを割り当てる" width="2872" height="1042" data-path="assets/images/agents/telephony/phone-number-details.png" />
    </Frame>
  </Tab>

  <Tab title="CLI">
    ```zsh lines theme={null}
    cartesia phone-numbers assign <phone-number-id> --agent-id <agent-id>
    ```

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

    ```zsh lines theme={null}
    cartesia phone-numbers unassign <phone-number-id>
    ```

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

    ```zsh lines theme={null}
    cartesia phone-numbers ls --type twilio
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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` に設定します。
  </Tab>
</Tabs>

## インバウンド通話

誰かがあなたの Twilio 番号に発信すると、割り当てられた Cartesia エージェントに接続されます。

<Tip>
  リージョンやユースケースごとに複数の番号を同じエージェントに割り当てることができます。たとえば、米国のサポートラインと英国のサポートラインの両方を 1 つのエージェントで処理することも可能です。
</Tip>

## アウトバウンド通話

エージェントは、Twilio の標準料金で国際番号を含む任意の電話番号に通話を発信できます。

<Tabs>
  <Tab title="Playground">
    エージェントページまたは CLI からアウトバウンド通話をトリガーします：

    ```bash theme={null}
    cartesia call <phone_number> <agent_id>
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

アウトバウンド通話は、電話番号のプロバイダーに紐付けられた認証情報を使用します。`us1` プロバイダーは米国の Twilio エッジ経由でルーティングされ、`ie1` プロバイダーはアイルランド経由でルーティングされます。詳細は [リージョナルルーティング](/line/integrations/telephony/twilio/regional-routing) を参照してください。

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

ダウンタイムなしで Twilio API キーをローテーションします：

1. Twilio で新しい API キーを作成します（上記のステップ 2）
2. Cartesia のプロバイダーを更新します：

<Tabs>
  <Tab title="Playground">
    **Phone Numbers** → **Settings** に移動し、Twilio アカウントの認証情報を更新します。
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

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

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

## 番号の削除

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

## 次のステップ

* [最初のアウトバウンド通話を発信する](/line/integrations/telephony/outbound-dialing)
* マルチリージョンデプロイメント用に [リージョナルルーティングを設定する](/line/integrations/telephony/twilio/regional-routing)
* [Phone Numbers API](/api-reference/agents/phone-numbers/list) および [Providers API](/api-reference/agents/providers/list) を確認する