ThunderPhone v3、提供開始。セルフサービスで、1分あたり2セントから。発表内容を見る

Developer cookbook

Slackまたはチャットアプリから通話を実行

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

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

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

全体の仕組み

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

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

開始前の準備

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

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

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

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 署名を検証するを参照してください。
  • エンベロープの event_id で重複を排除し、position 順に並べます。 配信は少なくとも 1 回行われ、ターンは順不同で到着する可能性があります。
  • 通話中でスレッドが過剰に更新される場合は、行をバッチ処理します。1 行ごとに 1 メッセージを投稿するより、数秒ごとに投稿する方が読みやすくなります。

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

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

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

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 接続として作成し、エージェントにリンクします。 すべてのツールリクエストには、X-ThunderPhone-Call-ID ヘッダーで通話情報が渡されます。

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

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

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

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

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 までに誰も回答しなかった場合、エージェントには回答が届かなかったことが伝えられ、相手に次の手順を案内します。通話に対する質問が保留中の場合、そのスレッド内の次の返信が質問への回答になります。ツール結果として配信し、ささやきとしても送信しないでください(ささやきはツールが返った後にのみエージェントへ届きます)。 長時間の待機を参照してください。

リクエスト内で待機する(最大 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 分を超える可能性がある回答には、この方法を使用してください。通話は保留されません。その間に何をすべきかをプロンプトでエージェントに指示します。たとえば、相手の話し相手を続ける、または折り返し電話を提案します。

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

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 の組織の webhook シークレットを使用します。
  • 通話を開始できるユーザーを決定してください。発信前に Slack ユーザー ID を確認します。
  • 発信通話には、他のすべての通話と同じルールが適用されます。発信通話に関する法律を参照してください。

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

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