# Summaries API

API経由で、2種類のAI生成要約を利用できます。

- **チャット要約** — 特定の連絡先との会話の短い要約で、オンデマンドで生成されます。チャット内の要約コントロールと同じものです（[チャット要約](../chats/chat-interface.md#chat-summary)を参照）。
- **日次要約** — [日次要約](../daily-summaries/daily-summaries.md)が毎朝作成する、すべての会話を対象とした1日1回のまとめです。統計情報、セクションごとのMarkdownブロック、およびAIがそれに基づいて作成したタスクが含まれます。

- **ベースURL** — `https://api.dmchamp.com/v1`
- **認証** — APIキー（[認証](authentication.md)を参照）。[スコープ付きキー](api-keys.md#scoped-keys)には `Summaries` セクションが必要です。
- **エラーとページネーション** — [エラーとページネーション](errors-and-pagination.md)を参照してください。

以下のすべての例では、cURLでの `?apiKey=` クエリ形式と、JavaScriptおよびPythonでの `X-API-Key` ヘッダーを示しています。どちらの方法もすべてのエンドポイントで使用可能です。

---

## チャット要約の生成

`POST /summaries` — 連絡先の `phoneNumber`（国番号付き）または `email` を送信します。いずれか一方が必須です。

AIは、その連絡先の最も最近**終了した**会話、またはまだ終了していない場合は現在進行中の会話を読み取り、その要約を作成します。要約は連絡先に保存され（アプリの連絡先パネルの「**要約**」の下に表示されます）、レスポンスとしても返されるため、CRM、Slackチャンネル、またはメールに直接転送できます。

**コスト:** エージェントのAI品質ティアにおけるAI返信1回分と同じです（Proは1クレジット、Maxは0.25、Miniは0.15）。独自のAnthropicキーを接続している場合、Proのコストは0になります。残高が不足している場合、生成が行われる前にリクエストは拒否されます。

**cURL**

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+31612345678"}'
```

**JavaScript**

```javascript
const res = await fetch("https://api.dmchamp.com/v1/summaries", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ email: "jane@example.com" }),
});
const { summary } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://api.dmchamp.com/v1/summaries",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phoneNumber": "+31612345678"},
)
print(r.json()["summary"])
```

**レスポンス**

```json
{
  "success": true,
  "message": "Chat summary generated successfully",
  "summary": "Jane asked about the 10-session package for her two children (ages 6 and 9) and preferred Saturday mornings. She booked a trial lesson for Saturday at 10:00 and wants to know whether siblings get a discount."
}
```

| ステータス | 意味 |
|---|---|
| `400` | `phoneNumber` と `email` のどちらも送信されませんでした。 |
| `404` | 一致する連絡先がない、連絡先にまだ会話がない、または会話にメッセージが含まれていません。詳細はレスポンスボディの `message` を確認してください。 |
| `500` | 生成に失敗しました（クレジット不足など）。 |

> **自動化レシピ：要約付きの予約メール。** 「**予約完了**」トリガーの[自動化](../automations/automations.md)で、`${trigger.contact.phone_number}`（または連絡先のメールアドレス）を指定してこのエンドポイントを呼び出す「**HTTPリクエスト**」ステップを追加します。次に、HTTPステップのレスポンスから `summary` を挿入し、チャットへのリンク（アプリのアドレスの後に `/chats/` とトリガーからの連絡先IDを続けたもの）を添える「**メール**」ステップを追加します。これにより、チームは受信トレイを開くことなく、同じメール内で予約のコンテキストを把握できます。

> **要約の読み込みについて。** 保存されたチャット要約を一覧表示するエンドポイントはありません。後で必要になる場合はレスポンスのテキストを保持しておくか、再度生成してください（呼び出しごとに課金されます）。

### 代替手段：連絡先IDによる指定

`POST /summaries/chat-summary` に `{"contactId": "..."}` を指定すると、すでにIDを保持している連絡先に対して同様の生成が行われます。これは成功（`{"success": true, "data": "Chat summary generated successfully"}`）を確認するだけで、テキスト自体は**返されません**。要約そのものが必要な場合は `POST /summaries` を使用してください。割り当てられた連絡先にのみアクセス権を持つチームメンバーが、その範囲外の連絡先に対して実行した場合は `404` が返されます。

---

## 日次要約の取得

`GET /summaries/daily/{date}` — `date` は `YYYY-MM-DD` です。その日の要約、またはまだ生成されていない場合は `summary` に `null` を返します。さらに、設定したセクション構成も含まれます。

**cURL**

```bash
curl "https://api.dmchamp.com/v1/summaries/daily/2026-09-08?apiKey=YOUR_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "data": {
    "summary": {
      "date": "2026-09-08",
      "status": "completed",
      "generated_at": "2026-09-09T05:02:11.000Z",
      "stats": {
        "total_conversations": 42,
        "total_messages_sent": 310,
        "total_messages_received": 268,
        "human_alerts": 3,
        "bookings": 5,
        "new_contacts": 11,
        "sales": 2
      },
      "sections": {
        "wins_losses_improvements": "## Wins\n- ...",
        "tasks_action_items": "- Call Jane back about the sibling discount",
        "human_alerts_reviews": "...",
        "sentiment_analysis": "...",
        "booked_meetings_sales": "..."
      },
      "contact_map": { "Jane Doe": "uid_whatsapp_31612345678" },
      "auto_tasks": [],
      "created_task_ids": []
    },
    "section_configs": [
      { "id": "wins_losses_improvements", "name": "Wins, Losses & Improvements", "enabled": true, "position": 0 }
    ]
  }
}
```

- **`status`** — `pending`、`generating`、`completed`、または`failed`（`error`が設定されている場合）。再生成後、このエンドポイントをポーリングして`completed`と表示されるまで確認してください。
- **`sections`** — セクションIDごとにキー付けされた、セクションごとのMarkdown文字列。5つの標準セクションは`wins_losses_improvements`、`tasks_action_items`、`human_alerts_reviews`、`sentiment_analysis`、`booked_meetings_sales`です。「Daily Summaries」ページの「Configure」で追加したセクションには`custom_…` IDが付与されます。名前と順序は`section_configs`でエコーされます。
- **`contact_map`** — 表示名から連絡先IDへのマッピング。テキスト内の名前をリンクに変換できます。
- **`auto_tasks`** / **`created_task_ids`** — AIが抽出したアクションアイテムと、それに基づいて作成されたタスク（「Create task cards from action items」がオンの場合）。

| ステータス | 意味 |
|---|---|
| `400` | `date`が`YYYY-MM-DD`ではない、または未来の日付です。 |
| `403` | アカウントでDaily Summariesが無効になっています。 |

> ポーリングよりもプッシュ通知をご希望ですか？**Daily Summary Created** [webhookイベント](../integrations/webhooks.md)を使用すると、朝のサマリーが完了した瞬間に同じペイロードが配信されます。

---

## デイリーサマリーの再生成

`POST /summaries/daily/{date}/regenerate` — その日の新しい生成をバックグラウンドで開始し、`status: "generating"`と空の`sections`を即座に返します。完了するまで`GET /summaries/daily/{date}`をポーリングしてください。アプリ内の「Try again」リンクと同じルールが適用されます。

オプションのボディ`{"deleteTasks": false}`は、前回の実行で作成されたタスクを保持します。デフォルトでは、タスクは削除され、新しいサマリーから再作成されます。真偽値を送信してください。文字列`"false"`は無視され、デフォルトとして扱われます。

```bash
curl -X POST "https://api.dmchamp.com/v1/summaries/daily/2026-09-08/regenerate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deleteTasks": false}'
```

---

## クイックリファレンス

| タスク | エンドポイント |
|---|---|
| チャットサマリーを生成してテキストを取得する | `POST /summaries` |
| 連絡先IDでチャットサマリーを生成する（テキストは返されません） | `POST /summaries/chat-summary` |
| その日のサマリーを読み取る | `GET /summaries/daily/{date}` |
| その日のサマリーを再生成する | `POST /summaries/daily/{date}/regenerate` |