発信通話を行う（API）

独自のコードからAI駆動の発信通話をトリガーします。アンケート、フォローアップ、確認フローに対応。

発信通話では、宛先番号とエージェント設定をThunderPhoneに渡すことで、AIが代わりに通話を発信します。主なユースケース:

• 予約確認
• アンケートの折り返し
• 不在着信後の「再試行」フォローアップ
• 配車・派遣形式の通知

前提条件#

1. 発信対応の番号を選択

   VoIP接続を通じて所有している番号を使用するか、Phone Numbers ページから ThunderPhone の番号を発信に使用する許可を申請します。ThunderPhone の番号は最初は着信専用です。ThunderPhone は各申請を手動で審査します。承認されると、それらの番号では承認済みの1日の上限まで通話を発信でき（上限は UTC 00:00 にリセット）、キャンペーンを実行できます。また、より高い上限を申請することもできます。顧客の VoIP 番号には1日の上限がないため、発信にはこちらを推奨します。 独自の番号を使用するを参照してください。

2. エージェントを作成

   発信向けのプロンプトでは、通常、エージェントが自己紹介と目的の説明から始めます。たとえば「こんにちは、Acme の者です。明日午後3時の予約確認のためにお電話しています…」のようになります。outbound_speak_order を agent_first（デフォルト）に設定します。

3. 残高をプラスに維持

   残高が $0.00 以下の場合、発信は 402 Payment Required を返します。ダッシュボードの 組織 → 請求設定 でチャージするか、自動リロードを有効にします。sk_live_ キーではGET /v1/billingで残高を確認できますが、チャージや自動リロードの変更はできません。

保存済みエージェントで通話を発信#

最も簡単な方法は、IDでエージェントを参照することです。

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":   "+14155552671",
    "agent_id":    12
  }'

レスポンス:

{ "call_id": 987654321, "status": "initiated" }

インライン設定で通話を発信#

エージェントとして保存する必要のない一回限りのプロンプトの場合は、 代わりにconfigを渡します。形式は call.incoming webhookの レスポンススキーマと一致します。

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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

通話を追跡する#

並行して、 telephony.complete Webhook を購読してください。これは通話の終了を最も迅速に把握する方法です。受信Webhookを受け付けられない場合は、数秒ごとに GET /v1/calls/{call_id} をポーリングしてください。通話が終了すると、レコードには end_reason、duration_seconds、録音URLが含まれます。

エージェントが通話後に構造化データを抽出するよう設定されている場合、そのデータは確定処理の完了後に別途配信されます。

保存済みエージェントに通話ごとの変数を渡す#

保存済みエージェントでは、プロンプトテキスト内で {{name}} や {{name|there}} のようなプレースホルダーを使用できます。agent_id を指定して発信する場合は、その通話の値を含む variables を渡します。

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

プレースホルダー名をキーとする文字列値を使用してください。これらの変数は保存済みエージェントに適用されます。このガイドのインライン config の例では使用しません。

対応すべき障害モード#

安定版の適格性コードの完全な一覧と、両方の 409 レスポンス形式については、発信通話リファレンスを参照してください。 リクエストが受け付けられた後、通話が発信される前に有効な番号が不適格になった場合、最終チェックで再試行不可の 409 ペイロードが返されます。

保留時間を制御する#

相手の応答が遅いことで長時間化する発信通話 （IVRツリー、キュー）は、max_hold_seconds で上限を設定できます。

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

直近のN秒間に人間の音声を受信していない場合、エージェントは通話を切断します。デフォルトは900秒（15分）です。

次のステップ#