> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 電話番号

> テレフォニープロバイダーで電話番号を検索、購入、登録します。発信方法は[通話](/jp/guides/call-outcomes)を参照してください。

## 概要

電話通話はテレフォニープロバイダー経由で行います。番号を取得する方法は **3 つ** あります：

| パス                                    | 使うタイミング                                        | インテグレーション必要？ |
| ------------------------------------- | ---------------------------------------------- | ------------ |
| **A — 番号を検索して選ぶ**                     | 在庫から特定の番号を選びたい場合                               | 不要           |
| **B — 番号を自動割り当て**                     | 最速のセットアップ — エージェント ID を渡すだけで OneInbox が番号を割り当て | 不要           |
| **C — 自分の番号を持ち込む（Twilio または Telnyx）** | Twilio または Telnyx で番号を既に所有しており、それを使い続けたい場合     | 必要           |

いずれかのパスを選んで番号を登録し、その後[通話](/jp/guides/call-outcomes)へ進んで発信してください。

***

## パス A — 番号を検索して選ぶ

利用可能な番号を検索し、希望する番号を購入します。OneInbox が購入とエージェントへの紐付けを一度に行います。

**1. 利用可能な番号を検索**

```bash theme={null}
curl "https://api.oneinbox.ai/v1/phone-numbers/search?country=US&area_code=415&limit=10" \
  -H "Authorization: Bearer <api_key>"
```

**2. 特定の番号を購入**

検索結果から `phone_number` をコピーして購入エンドポイントに渡します：

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Sales Line",
    "agent_id": "<agent_id>",
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "fallback": { "agent_id": "<fallback_agent_id>" },
      "voicemail_message": "Sorry we missed you, please leave a message."
    }
  }'
```

インバウンド通話を受けたい場合は `inbound_routing` を含めます。アウトバウンドのみの場合は省略してください。

番号はエージェントに割り当て済みです。[通話](/jp/guides/call-outcomes)へ進んで最初の発信をしてください。

***

## パス B — 番号を自動割り当て（最速）

番号を検索したくない場合は `phone_number` を省略してください。OneInbox が利用可能な番号を自動で選択し、1 回の API 呼び出しでエージェントに紐付けます：

```bash theme={null}
curl -X POST https://api.oneinbox.ai/v1/phone-numbers/purchase \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "area_code": "415",
    "friendly_name": "Sales Line",
    "agent_id": "<agent_id>",
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "fallback": { "agent_id": "<fallback_agent_id>" },
      "voicemail_message": "Sorry we missed you, please leave a message."
    }
  }'
```

インバウンドが必要な場合は `inbound_routing` を含め、アウトバウンドのみの場合は省略してください。レスポンスに割り当てられた `phone_number` が含まれます。[通話](/jp/guides/call-outcomes)へ進んで最初の発信をしてください。

***

## パス C — 自分の番号を持ち込む（Twilio または Telnyx）

Twilio または Telnyx で既に所有している番号を使用します。どちらも同じ手順です：SIP トランクを設定し、OneInbox でインテグレーションを作成し、番号を登録します。

<Tabs>
  <Tab title="Twilio">
    **1. Twilio で番号を購入**
    [Twilio コンソール](https://console.twilio.com) → Phone Numbers → Manage → Buy a number から電話番号を購入します。

    **2. Elastic SIP トランクを設定**
    OneInbox は Elastic SIP Trunking 経由で Twilio に接続します。

    <Accordion title="Twilio での Elastic SIP トランクの設定方法">
      **ステップ 1 — トランクを作成**

      [Twilio コンソール](https://console.twilio.com) で左サイドバーの **Elastic SIP Trunking** → **Create new SIP Trunk** → 名前を付ける（例：「OneInbox Trunk」）→ **Create** をクリック。

      ***

      **ステップ 2 — Termination（アウトバウンド）を設定**

      Termination SIP URI は OneInbox がトランク経由でアウトバウンド通話を発信するために使用します。

      1. トランクを開いて **Termination** タブへ
      2. Twilio が **Termination SIP URI** を自動生成します — `yourtrunk.pstn.twilio.com` のような形式
      3. これをコピーします — OneInbox に渡す `sip_trunk` の値です

      ***

      **ステップ 3 — Origination（インバウンド）を設定**

      Origination URI は Twilio がインバウンド通話をどこに送るか（この場合 OneInbox）を指定します。

      1. トランクの **Origination** タブへ
      2. **Add new Origination URI** をクリック
      3. `sip:voice.oneinbox.ai:5060` を入力
      4. **Priority** を `10`、**Weight** を `10` に設定 → **Add** をクリック

      ***

      **ステップ 4 — 電話番号を紐付け**

      1. トランクの **Numbers** タブへ
      2. **Add a number** → ステップ 1 で購入した番号を選択
      3. **Add Selected** をクリック

      これで番号がこのトランク経由でルーティングされます。

      ***

      **ステップ 5 — 地理的アクセス許可を有効化（国際通話の場合）**

      国外（UAE、インドなど）への発信が必要な場合、これらの地域を有効化する必要があります：

      1. Twilio コンソールで **Voice** → **Settings** → **Geo Permissions** へ
      2. 発信したい国または地域を見つけてトグルをオン
      3. **Save** をクリック

      この設定がないと、国際番号へのアウトバウンド通話は `403 Forbidden` エラーで失敗します。

      ***

      これらの手順が完了したら、**Termination SIP URI**（例：`yourtrunk.pstn.twilio.com`）をコピーします — 以下で `sip_trunk` として渡します。
    </Accordion>

    **3. Twilio 認証情報を OneInbox に保存**
    Account SID と Auth Token は Twilio コンソール → Dashboard → Account Info で確認できます。

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/integrations \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My Twilio Account",
        "provider": "twilio",
        "api_key": "<your_twilio_auth_token>",
        "metadata": {
          "account_sid": "<your_twilio_account_sid>",
          "phone_number": "+15739693824",
          "sip_trunk": "<your_sip_trunk_domain>"
        }
      }'
    ```

    ```json theme={null}
    { "id": "crd_abc123", "provider": "twilio" }
    ```

    **4. OneInbox に番号を登録**

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+15739693824",
        "friendly_name": "Sales Line",
        "provider": "twilio",
        "agent_id": "<agent_id>",
        "provider_config": {
          "trunk_address": "yourtrunk.pstn.twilio.com",
          "auth_username": "oneinbox",
          "auth_password": "<your_sip_password>"
        },
        "inbound_routing": {
          "agent_id": "<routing_agent_id>",
          "fallback": { "agent_id": "<fallback_agent_id>" },
          "voicemail_message": "Sorry, we missed you. Please leave a message."
        }
      }'
    ```

    インバウンド通話を受けたい場合は `inbound_routing` を含めます。アウトバウンドのみの場合は省略してください。
  </Tab>

  <Tab title="Telnyx">
    **1. Telnyx で番号を購入**
    [Telnyx ポータル](https://portal.telnyx.com) → Numbers → Buy Numbers から電話番号を購入します。

    **2. SIP コネクションを設定**
    OneInbox は SIP コネクション（FQDN 接続）経由で Telnyx に接続します。

    <Accordion title="Telnyx での SIP コネクションの設定方法">
      **ステップ 1 — コネクションを作成**

      [Telnyx ポータル](https://portal.telnyx.com) で **Voice** → **SIP Connections** → **Add SIP Connection** をクリック。

      * **Connection name**: 例「OneInbox」
      * **Auth method**: Credential
      * **username** と **password** を設定します — これらが OneInbox で番号を登録する際の `auth_username` と `auth_password` になります

      ***

      **ステップ 2 — SIP トランクドメインを取得**

      コネクション作成後、Telnyx が SIP ドメインを割り当てます — `<yourconnection>.sip.telnyx.com` のような形式です。コピーしてください — OneInbox に渡す `sip_trunk` の値です。

      ***

      **ステップ 3 — インバウンド（オリジネーション）を設定**

      1. コネクションを開いて **Inbound** へ
      2. **SIP Trunking Settings** の下の発信先（オリジネーション）に `sip:voice.oneinbox.ai:5060` を設定

      ***

      **ステップ 4 — 電話番号を紐付け**

      1. **Numbers** → 購入した番号を選択
      2. **Connection/App** の下で作成した SIP コネクションを選択
      3. **Save** をクリック

      ***

      **ステップ 5 — 国際通話を有効化（必要な場合）**

      国外への発信が必要な場合：

      1. **Voice** → **Call Control** → **Outbound Voice Profile** へ
      2. **Destinations** の下で必要な国を有効化
    </Accordion>

    **3. Telnyx 認証情報を OneInbox に保存**
    API キーは Telnyx ポータル → Account → API Keys で確認できます。アカウント SID は Account → Overview にあります。

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/integrations \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My Telnyx Account",
        "provider": "telnyx",
        "api_key": "<your_telnyx_api_key>",
        "metadata": {
          "account_sid": "<your_telnyx_account_id>",
          "phone_number": "+15739693824",
          "sip_trunk": "<yourconnection>.sip.telnyx.com"
        }
      }'
    ```

    ```json theme={null}
    { "id": "crd_abc123", "provider": "telnyx" }
    ```

    **4. OneInbox に番号を登録**

    ```bash theme={null}
    curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{
        "phone_number": "+15739693824",
        "friendly_name": "Sales Line",
        "provider": "telnyx",
        "agent_id": "<agent_id>",
        "provider_config": {
          "trunk_address": "<yourconnection>.sip.telnyx.com",
          "auth_username": "<your_sip_username>",
          "auth_password": "<your_sip_password>"
        },
        "inbound_routing": {
          "agent_id": "<routing_agent_id>",
          "fallback": { "agent_id": "<fallback_agent_id>" },
          "voicemail_message": "Sorry, we missed you. Please leave a message."
        }
      }'
    ```

    インバウンド通話を受けたい場合は `inbound_routing` を含めます。アウトバウンドのみの場合は省略してください。
  </Tab>
</Tabs>

```json theme={null}
{
  "id": "phn_abc123",
  "phone_number": "+15739693824",
  "agent_id": "agt_abc123",
  "status": "active"
}
```

後で別のエージェントに番号を再割り当てするには、[PATCH 電話番号更新](/api-reference/phone-numbers/update-phone-number) で `{ "agent_id": "..." }` を使用してください。

***

## インバウンド通話

番号がインバウンド通話を受けるようにするには、番号を登録または購入する際に `inbound_routing` を設定します（上記のパス A、B、C を参照）。`inbound_routing` がない場合、番号はアウトバウンドのみになり、着信はエージェントにルーティングされません。

既存の番号にインバウンドルーティングを追加・更新するには、[PATCH 電話番号更新](/api-reference/phone-numbers/update-phone-number) を使用します：

```bash theme={null}
curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<new_agent_id>" }'
```

### インバウンドルーティング

`inbound_routing` を使って、インバウンド通話を処理するエージェントを制御します — アウトバウンドと同じエージェントでも別のエージェントでも使えます。フォールバックエージェントやカスタムボイスメールメッセージも任意で設定できます。

```bash theme={null}
# 番号を登録するときに inbound_routing を設定
curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "friendly_name": "Sales Line",
    "provider": "twilio",
    "agent_id": "<agent_id>",
    "provider_config": { ... },
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "fallback": {
        "agent_id": "<fallback_agent_id>"
      },
      "voicemail_message": "Sorry, we missed you. Please leave a message."
    }
  }'

# または既存の番号のルーティングを更新
curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "voicemail_message": "Updated voicemail message."
    }
  }'
```

| フィールド                               | 役割                                                 |
| ----------------------------------- | -------------------------------------------------- |
| `inbound_routing.agent_id`          | インバウンド通話を処理するエージェントを上書き — 番号のプライマリ `agent_id` とは独立 |
| `inbound_routing.fallback.agent_id` | プライマリのルーティングエージェントが利用できない場合にルーティングするエージェント         |
| `inbound_routing.voicemail_message` | この番号のカスタムボイスメールメッセージ、エージェントのデフォルトを上書き              |

***

## 電話番号を管理する

### 電話番号を取得する

単一の番号の現在の設定（エージェントの割り当て、インバウンドルーティング、プロバイダー詳細）を取得します。

```bash theme={null}
curl https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>"
```

### 電話番号を削除する

アカウントから番号を解放します。OneInbox 経由で購入した番号の場合、キャリアでもキャンセルされます。

```bash theme={null}
curl -X DELETE https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>"
```

***

## API リファレンス

[電話番号を登録](/api-reference/phone-numbers/register-phone-number) · [電話番号を更新](/api-reference/phone-numbers/update-phone-number) · [電話番号一覧](/api-reference/phone-numbers/list-phone-numbers) · [電話番号を取得](/api-reference/phone-numbers/get-phone-number) · [電話番号を削除](/api-reference/phone-numbers/delete-phone-number)