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

# 概要

> 発信前の確認、二重発信の防止、結果の受け取りまでの流れです。

## 1. 発信前に確かめる（任意）

[発信前の確認](https://docs.ai-call.co/calls/preflight.md)は、電話をかけずに、発信を止める理由がないかを返します。

```bash theme={null}
curl https://api.ai-call.co/calls/preflight \
  -H "Authorization: Bearer $AICALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "0123456789abcdef01234567", "to": "090-1234-5678"}'
```

```json theme={null}
{
  "ok": false,
  "to": "+819012345678",
  "problems": [{ "code": "outside_calling_hours", "message": "発信できる時間帯（日本時間 09:00〜20:00）の外です。" }]
}
```

## 2. 電話をかける

```bash theme={null}
curl https://api.ai-call.co/calls \
  -H "Authorization: Bearer $AICALL_API_KEY" \
  -H "Idempotency-Key: order-1024" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "0123456789abcdef01234567",
    "to": "090-1234-5678",
    "purpose": "資料請求のお礼と面談のご案内",
    "contact": { "name": "山田", "company": "株式会社サンプル" },
    "variables": { "plan": "スタンダード" },
    "metadata": { "crm_id": "A-1024" }
  }'
```

```json theme={null}
{
  "id": "6730b7e4c0ffee0000000001",
  "status": "queued",
  "to": "+819012345678",
  "from": "+815012345678",
  "agent": { "id": "0123456789abcdef01234567", "name": "営業架電" },
  "metadata": { "crm_id": "A-1024" }
}
```

* `202` は「発信キューに入った」という意味です。同時通話枠（5件込み）が空き次第かけます。
* `contact` と `variables` は、この通話だけAIエージェントに渡す相手の情報です。保存済みの連絡先より優先されます。
* `metadata` は自由な値で、通話の取得結果と Webhook にそのまま返ります。自社のIDを入れておくと、結果を突き合わせやすくなります。

### 二重に電話をかけないために

`Idempotency-Key` ヘッダーは必須です。通信エラーなどで同じリクエストを送り直しても、24時間以内に同じキー・同じ内容なら最初の結果を返し、電話は一度しかかけません。

* 1件の発信ごとに一意の値（自社の注文IDなど）を使ってください。
* 同じキーで内容が違うと `422 idempotency_key_reused` になります。
* 架電禁止・時間外・残高不足などで断られたリクエストのキーは、原因を直してから使い直せます。

### 発信を止める確認

次のどれかに当たると、電話はかけずにエラーを返します。API から外すことはできません。

* 電話番号の形式（日本国内の番号のみ。フリーダイヤル等は不可）
* AIエージェント（このアカウントのもので、会話が設定済み）と発信元の電話番号
* 架電しない設定・一時停止中の連絡先
* 発信できる時間帯（日本時間9:00〜20:00）
* 契約・残高
* 発信の上限（1分60件・24時間2000件）

## 3. 結果を受け取る

通話が終わったら、[Webhook](https://docs.ai-call.co/webhooks/overview.md) の `call.ended` で結果が届きます。または[通話を取得する](https://docs.ai-call.co/calls/get.md)で確かめられます。

```bash theme={null}
curl https://api.ai-call.co/calls/6730b7e4c0ffee0000000001 \
  -H "Authorization: Bearer $AICALL_API_KEY"
```

主な `result`：

| result | 意味 |
| - | - |
| `completed` | 通話して終わった |
| `no_answer` | 不在（出なかった） |
| `busy` | 話し中 |
| `rejected` | 着信拒否 |
| `invalid_number` | 存在しない番号 |
| `voicemail` | 留守番電話 |
| `failed` | 発信できなかった（`failure_reason` に理由） |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.