> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/serve/call-center-outbound-api.md).

# コールセンター発信 API

外部システムからコールセンター発信 API を利用して、番号に紐づく Agent に電話を発信させ、通話記録 API で処理状況を確認します。

外部システムから API を通じて発信を開始し、指定した SIP 番号に紐づく Agent が相手と通話できます。たとえば、カスタマーサポートシステムで顧客の同意を得た後、折り返し電話のリクエストを送信し、返された通話記録 ID を保存して、接続の成否や終了時刻を後から確認できます。

SIP トランク、番号、Agent の管理画面での設定は、ユーザーマニュアルの[電話サポート（コールセンター）](https://docs.maiagent.ai/build/choose-channel/call-center)に従って、事前に完了してください。このページでは API 連携を説明します。管理画面の操作手順はマニュアルを参照してください。

## 呼び出しの前提条件 <a href="#prerequisites" id="prerequisites"></a>

* 組織でコールセンターが有効になっており、呼び出し元が組織のオーナー、またはコールセンター権限を持つメンバーであることが必要です。
* 現在の組織の SIP 番号 ID を使用してください。その番号が属するトランクで発信が有効になっており、発信回線が作成済みで、同期状態が同期済みであることが必要です。
* 番号に、音声機能を利用できる有効な Agent が紐づけられており、その Agent に API 会話プラットフォームがあることが必要です。

認証、API URL、JSON フィールドの形式は、[API 共通規約](https://docs.maiagent.ai/tech/ja/api-integration/api-conventions.md)に従います。以下のパスは `/api/v1/` を使用し、JSON は camelCase を使用します。

## 発信を開始する <a href="#start-outbound-call" id="start-outbound-call"></a>

```http
POST /api/v1/sip-numbers/{sipNumberId}/outbound-call/
```

`{sipNumberId}` は発信に使用する SIP 番号の ID であり、宛先の電話番号ではありません。リクエストボディには宛先番号のみを指定します。

| フィールド      | 必須 | 説明                                                                                               |
| ---------- | -- | ------------------------------------------------------------------------------------------------ |
| `toNumber` | はい | 宛先番号です。E.164 形式または SIP user part に対応しています。長さは 1～32 文字で、数字、英字、および `+`、`*`、`#`、`.`、`_`、`-` を使用できます |

Agent は SIP 番号の既存の紐づけによって決まるため、このリクエストで別途選択することはありません。システムは会話と発信通話記録を作成してから、ダイヤルを開始します。

成功すると `201 Created` と通話記録オブジェクトが返されます。まず、その `id` を保存してください。初期ステータスは `initiated`、方向は `outbound` です。

{% hint style="warning" %}
`201 Created` は発信が開始されたことを示します。相手が応答したことや、通話が完了したことを意味するものではありません。連携プログラムでは引き続き通話記録を照会してください。成功レスポンスだけで顧客への連絡が完了したと判断しないでください。
{% endhint %}

## 通話結果を照会する <a href="#query-call-result" id="query-call-result"></a>

返された通話記録の `id` を使用して照会します。

```http
GET /api/v1/calls/{callId}/
```

この照会にもコールセンター権限が必要です。取得できるのは、現在の組織に属し、削除されていない Agent の通話記録のみです。以下のフィールドで処理結果を追跡できます。

| フィールド                             | 用途                              |
| --------------------------------- | ------------------------------- |
| `id`                              | 外部システムで通話を追跡する識別子として保存します       |
| `status`                          | 現在の通話ステータスです。下表を参照してください        |
| `direction`                       | このフローで作成された通話は `outbound` になります |
| `chatbot`、`conversation`          | この通話で使用する Agent と会話の識別子です       |
| `fromNumber`、`toNumber`           | 発信元番号と宛先番号です                    |
| `answeredAt`、`endedAt`、`duration` | 応答時刻、終了時刻、通話時間（秒）です             |
| `disconnectReason`                | システムが記録した切断理由です                 |

| ステータス         | 意味         |
| ------------- | ---------- |
| `initiated`   | 発信開始済みです   |
| `ringing`     | 呼び出し中です    |
| `in-progress` | 通話中です      |
| `completed`   | 完了しました     |
| `failed`      | 失敗しました     |
| `busy`        | 話し中です      |
| `no-answer`   | 応答がありません   |
| `canceled`    | キャンセルされました |

`initiated`、`ringing`、`in-progress` は処理中の状態で、それ以外は終了状態です。外部システムは終了状態を取得した後、この通話の追跡を停止できます。

## 発信開始に失敗した場合の対処 <a href="#handle-start-failure" id="handle-start-failure"></a>

発信が無効、トランクが未同期、有効な Agent がない、または API 会話プラットフォームがない場合は、発信開始前にリクエストが拒否されます。設定を修正してから再試行してください。バリデーションエラーの共通形式は、[API 共通規約：エラーレスポンス](https://docs.maiagent.ai/tech/ja/api-integration/api-conventions.md#errors)を参照してください。

ダイヤル要求の送出に失敗すると、発信エンドポイントは `400` を返します。発信開始エンドポイントを呼び出すたびに、新しい通話が作成される可能性があります。重複した折り返し電話を避けるため、再試行する前に既存の通話記録を確認してください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/ja/serve/call-center-outbound-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
