---
title: "Slackまたはチャットアプリから通話を実行"
description: "公開APIを使用して、通話を開始し、通話をリアルタイムで追跡し、エージェントを誘導して質問に回答する独自のSlack、Teams、またはウェブチャットボットを構築します。"
---

チームで既に使用しているチャットアプリからエージェントを操作できます。メッセージを送信すると通話が開始されます。通話の内容はスレッドにリアルタイムで表示されます。スレッド内の返信でエージェントを誘導できます。エージェントが判断を必要とする場合は、その場で質問し、回答を待ちます。

ThunderPhone はこのボットをホストしません。チャットアプリをパブリック API に接続する小さなサーバーを、設定したチーム側（またはコーディングエージェント）が構築します。このページでは必要な要素を説明します。Slack、Microsoft Teams、Discord、プライベートなウェブチャットページのいずれでも同じで、例では Slack を使用します。

## 全体の仕組み

| チャットで行う操作 | ボットが呼び出すもの | 起こること |
|---|---|---|
| 「Comcast に電話して障害復旧予定時刻を確認して」と送信 | メッセージを `context` として含む [`POST /v1/call`](/api-reference/outbound-calls) | エージェントが発信します。ボットが通話用のスレッドを作成します |
| スレッドを確認 | [`telephony.turn`](/ja/webhooks/events) Webhook を受信 | エージェントまたは相手が発話した各行がスレッドに表示されます |
| 通話中にスレッドで返信 | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | エージェントはメモを非公開で受け取り、それに基づいて行動します。相手に聞こえることはありません |
| エージェントの質問に回答 | [ツールエンドポイント](/ja/guides/build-tool-integration)が回答を返すか、[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) で後から回答を配信 | エージェントはその回答を使って通話を続けます。保留モードでは、その間、相手には保留音が流れます |
| 結果を確認 | [`telephony.complete`](/ja/webhooks/events) Webhook を受信 | ボットが要約と結果を投稿します |

ボットでは、どのチャットスレッドがどの `call_id` に対応するかという 1 つのマッピングを保持します。

## 開始前の準備

- **APIキー**。サーバー上で保管し、ブラウザやチャットには保存しないでください。
  **連携 → APIキー** で作成します（[サーバーAPIキーを作成](/ja/guides/api-keys)を参照）。
- 通話用の**発信可能な番号とエージェント**。メッセージは通話ごとの `context` になるため、汎用エージェント1つですべてのタスクを処理できます。
- Railway、Fly.io、Render、または独自ホストなど、Webhookを受信できる**サーバー**。
- そのサーバーを指し、`telephony.turn` と `telephony.complete` を購読する**Webhookエンドポイント**。ターンイベントは、それらを指定しているエンドポイントにのみ送信されます。[Webhook](/ja/webhooks/endpoints)を参照してください。
  ターンイベントにはエージェントの通話録音を有効にする必要があり、通話終了時の
  `summary` にはエージェントの **通話要約を生成** 設定が必要です。これらがない場合、該当フィールドは空のままです。
- **独自のチャットアプリ。** Slackの場合は、[api.slack.com/apps](https://api.slack.com/apps) でワークスペース用のアプリを作成します。

<Tip>
  自身のワークスペース用に作成した Slack アプリを使用し、チャンネル履歴を読み取るのではなく Slack の Events API でメッセージを受信してください。Slack は、Marketplace 外で他のワークスペースに配布されるアプリに厳しい読み取り制限を設けています。自身のワークスペース用に構築したアプリはその制限の対象ではなく、読み取りを行わなくてもイベントを発生時に受信できます。一般的なボットスコープは、`chat:write`、`app_mentions:read`、`im:history`（ダイレクトメッセージ）、`channels:history`、`groups:history`（ボットが参加しているパブリックおよびプライベートチャンネルのスレッド返信）です。ボットイベント `app_mention`、`message.im`、`message.channels`、`message.groups` を購読し、App Home の Messages タブを有効にして、ユーザーがボットにダイレクトメッセージを送れるようにします。
</Tip>

## 1. メッセージから通話を開始する

ボットがメッセージ（ダイレクトメッセージまたは @メンション）を受信したら、
Slack のリクエストをすぐに確認応答し（Slack は 3 秒以内に確認応答されない
リクエストを再試行します）、残りの処理はバックグラウンドで実行します。送信者に
通話を発信する権限があることを確認してから、メッセージを `context` として通話を開始します。

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'
```

返された `call_id` を Slack スレッド（`channel` とメッセージの
`ts`）に関連付けて保存し、スレッドに返信します（「通話中…」）。`idempotency_key`
はチャネルとメッセージの `ts` から作成します（`ts` は同じチャネル内でのみ一意です）。
これにより、再試行された Slack イベントによって 2 回目の通話が発信されることを防げます。
リクエストで番号ではなく人物が指定されている場合、ボットは先にその番号を検索します。
ThunderPhone が発信するのは、送信した `to_number` のみです。

## 2. スレッドで通話を追跡する

各 `telephony.turn` webhook には、`call_id`、話者（`role`：
エージェントの場合は `assistant`、相手の場合は `user`）、`text`、
およびターンの `position` が含まれます。`call_id` でスレッドを検索し、
その行を投稿します。

- 操作する前に、**すべての webhook を検証します**。詳細は
  [webhook 署名を検証する](/ja/guides/verify-webhook-signatures)を参照してください。
- **エンベロープの `event_id` で重複を排除し、`position` 順に並べます。**
  配信は少なくとも 1 回行われ、ターンは順不同で到着する可能性があります。
- 通話中でスレッドが過剰に更新される場合は、**行をバッチ処理します**。1 行ごとに
  1 メッセージを投稿するより、数秒ごとに投稿する方が読みやすくなります。

`telephony.complete` を受信したら、通話の終了方法（`status` と
`end_reason`）、`summary`、抽出されたデータを投稿し、スレッドを完了します。
フィールドについては、[通話完了](/ja/webhooks/call-complete)を参照してください。

## 3. スレッドから通話を誘導する

誰かが進行中の通話のスレッドに返信した場合、エージェントが質問への回答を待っている
（ステップ 4）場合を除き、返信をささやきとして送信します。この場合、返信が回答になります。

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'
```

エージェントはこれを非公開で聞き、次のターンに組み込みます。相手がささやき自体を
聞くことはありません。ささやきは 1 ～ 1000 文字です。`409` は通話がすでに終了して
いることを示します。スレッドに通話が終了したことを通知してください。

## 4. エージェントから質問できるようにする

エージェントに、たとえば `question` パラメータを 1 つ持つ `ask_owner` ツールを与え、サーバーを呼び出すようにします。これを [API 接続](/ja/guides/build-tool-integration)として作成し、エージェントにリンクします。
すべてのツールリクエストには、`X-ThunderPhone-Call-ID` ヘッダーで通話情報が渡されます。

回答を返す方法は 3 つあります。

**通話を保留（最長10分）。** ツールを保留モードに設定します: `spec.wait_mode`
`"hold"` と `spec.timeout` を最大600秒に設定します（タイムアウトを設定しない場合、保留は
20秒間継続します）。設定は
[API](/api-reference/integrations#timeout-and-wait-mode) で行うか、Zeus に
設定を依頼します（アプリのエディターにはまだどちらのフィールドもありません）。エンドポイントは質問を通話のスレッドに投稿し、直ちに保留中の結果を返します:

```json
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}
```

相手にはエージェントから 1 文が聞こえた後、保留音が流れます。電話メニューまたは留守番電話では、エージェントは代わりに音声による更新を使用します。全二重エージェントは保留せず、保留中の返信を結果として受け取ります。スレッドに返信が届いたら、
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) を使用して配信します。

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'
```

保留音がフェードアウトし、エージェントは回答を使って会話を続けます。`timeout` までに誰も回答しなかった場合、エージェントには回答が届かなかったことが伝えられ、相手に次の手順を案内します。通話に対する質問が保留中の場合、そのスレッド内の次の返信が質問への回答になります。ツール結果として配信し、ささやきとしても送信しないでください（ささやきはツールが返った後にのみエージェントへ届きます）。
[長時間の待機](/ja/tools/overview)を参照してください。

**リクエスト内で待機する（最大 3 分）。** エンドポイントは質問を投稿し、返信を待ってから、たとえば `{"answer": "Yes, book Tuesday at 10."}` を返します。
API を通じてツールの `spec.timeout` を最大 180 秒に設定します（デフォルトは 20 秒です）。誰も回答しなかった場合でもエージェントが対応できる内容を返せるよう、エンドポイントには数秒短い独自の期限を設定します（例: 170 秒）。たとえば
`{"answer": null, "note": "No reply yet. Offer to take a message."}` を返します。`timeout` に達したツールはエージェントにエラーとして届くため、ホストはその時間だけリクエストを開いたままにする必要があります。待機中、エージェントは相手に確認中であることを伝え、約 12 秒後にまだ処理中であることを伝え、その後は約 15 秒ごとに短い更新を伝えます。ここでも保留モードを使用できます。`spec.wait_mode` を `"hold"` に設定すると、相手には更新の代わりに音楽が流れます。

**ささやきで回答する。** エンドポイントは質問を投稿し、たとえば `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}` を直ちに返します。
返信が届いたら、ささやきとして送信し（ステップ 3）、エージェントはすぐに応答します。10 分を超える可能性がある回答には、この方法を使用してください。通話は保留されません。その間に何をすべきかをプロンプトでエージェントに指示します。たとえば、相手の話し相手を続ける、または折り返し電話を提案します。

どの場合でも、ツールをいつ使用するか、待機中に相手へ何を伝えるかをエージェントのプロンプトに記載します。

```text
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.
```

## 考慮すべき制限

- エンドポイントは、ツールの `timeout` 以内、かつ最大 **180秒** で応答する必要があります。保留モードのツールは、保留中の結果とともに最大 **600秒** 通話を保留にできます。
- ツールの待機中、エージェントは相手に応答しません。保留モードでは音楽が流れ、それ以外では短い音声の更新を伝えます。
- ささやきは最大 **1000文字** です。
- `telephony.turn` の配信は少なくとも1回行われ、順序が前後する場合があります。

## セキュリティチェックリスト

- API キーはサーバー上で保持してください。
- webhook とツールリクエストでは ThunderPhone の署名を、Slack のリクエストでは Slack の署名シークレットを検証してください。2種類の ThunderPhone 署名は異なるシークレットを使用します。webhook 配信では webhook エンドポイント固有のシークレットを使用し、ツールリクエストでは [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) の組織の webhook シークレットを使用します。
- 通話を開始できるユーザーを決定してください。発信前に Slack ユーザー ID を確認します。
- 発信通話には、他のすべての通話と同じルールが適用されます。[発信通話に関する法律](/ja/guides/outbound-calling-laws)を参照してください。

## コーディングエージェントで構築する

コーディングエージェントに[ドキュメント MCP サーバー](/ja/guides/docs-mcp)とこのページを参照させ、「このガイドに従う、自分の ThunderPhone エージェント用 Slack ボット」を作成するよう依頼してください。ThunderPhone アプリのアシスタントである Zeus は、エージェント側の設定（webhook エンドポイント、ツール、プロンプト行）を構成し、チャット内でボット用のスターターコードを作成できます。
