着信通話を処理する（API）
エンドツーエンドで、エージェントを設定し、電話番号に割り当て、通話を受け、文字起こしを確認します。
ターミナルから実行する、AIで電話に応答するための標準フローです。 以下を行います。
- プロンプトと音声を指定してエージェントを作成します。
- 電話番号をプロビジョニング（または持ち込み）し、エージェントを着信ハンドラーとして割り当てます。
- 番号に電話をかけます。通話ログ、文字起こし、録音を確認します。
API呼び出しは合計4回です。所要時間は5分未満です。
1. エージェントを作成する
エージェントには、通話を処理するプロンプト、音声、製品ティアがまとめられます。すべての設定フィールドについてはエージェントを参照してください。最小構成は次のとおりです。
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Support",
"prompt": "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
"voice": "john",
"product": "spark"
}'返された id を保存してください。ステップ2で必要になります。
2. 電話番号を取得する
発信先として使う番号だけが必要な場合は、ThunderPhoneのプールからデモ番号をプロビジョニングします。
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"area_code": "415"}'レスポンスには E.164 形式の id と number が含まれます。デモ番号は
status="provisioning" で開始し、数秒以内に active になります。必要に応じて
GET /v1/phone-numbers/{id}
をポーリングして状態遷移を確認してください。
3. エージェントを割り当てる
ステップ1で作成したエージェントを、番号の着信方向に関連付けます。
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'これで完了です。番号は利用可能になります。同じ PATCH で outbound_agent_id も設定すれば、その番号から発信する準備も整います。
4. 通話を受ける
電話からその番号に発信します。エージェントが応答し、プロンプトに従って自己紹介すると、会話が始まります。
通話中は、
GET /v1/calls
に status="in_progress" として表示されます。通話が終了すると、レコードは end_reason、duration_seconds、billable_minutes、および最終的には録音URLとAI評価で更新されます。
5. 結果を確認する
最近の通話一覧を取得します。
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"文字起こしを取得します。
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"録音URLも取得します（短時間のみ有効な署名付きURL）。
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"telephony.complete webhook
を購読している場合は、同じデータがサーバーへのPOSTとして送信されます。
call.complete
を参照してください。