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

Developer cookbook

View as Markdown
Open in
ClaudeChatGPTCursor

SIPで接続（電話番号不要）

PBX、通信事業者、またはSIPアプリケーションからThunderPhoneエージェントへ直接通話を送信します。通話ごとに1回限りのSIP URIを使用することも、恒久的なSIPアドレスを使用することもできます。

独自のシステムですでに電話番号を扱っている場合（PBX、コンタクトセンタープラットフォーム、または番号をローテーションする通信事業者アカウントなど）、通常のSIP経由でThunderPhoneエージェントに通話を送信できます。ThunderPhoneで番号をインポートまたは購入する必要はありません。システムからSIPアドレスに発信すると、エージェントが応答します。

SIPアドレスには2種類あります。

通話ごとのSIP URISIPエンドポイント
形式sip:c-<token>@sip.thunderphone.comsip:agent-<id>-<letters>@sip.thunderphone.com
作成方法通話ごとに1回、POST /v1/calls/register-sip1回だけ、POST /v1/sip-endpoints
認証アドレス内のワンタイムトークンSIPダイジェストのユーザー名とパスワード（必要に応じて送信元IP許可リスト）
適した用途通話転送前にすでにAPIを呼び出すアプリ、通話ごとの変数ThunderPhoneにトランクを向けるだけのPBXや通信事業者
有効期間5分間、1通話削除するまで

どちらの種類も組織内の1つのエージェントにルーティングされ、他のすべての着信通話と同様に通話履歴に表示されます。

通話ごとのSIP URI

1. 通話を登録する

curl -X POST https://api.thunderphone.com/v1/calls/register-sip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "to_number": "+14155550142",
    "variables": {"customer_name": "Ada"}
  }'
{
  "call_id": 862197007562,
  "sip_uri": "sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com",
  "expires_at": "2026-09-25T21:49:52Z",
  "agent_id": 12,
  "to_number": "+14155550142"
}
  • to_number（任意）は、設定側で発信者がダイヤルした番号です。通話履歴では通話の着信先として保存され、エージェントには自身の番号として表示されます。
  • variables（任意）は、発信通話と同様に、エージェントのプロンプト内の{{placeholders}}を埋めます。
  • call_idは、接続後に通話履歴（GET /v1/calls/{call_id}）で使用される通話IDです。

2. URIに発信する

5分以内に通話をsip_uriへ送信します。URIは1通話でのみ使用できます。通話に使用されると、その通話がすぐに終了した場合でも無効になります。

たとえばTwilioでは、引き継ぐ通話に対して次のTwiMLを返します。

<Response>
  <Dial>
    <Sip>sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp</Sip>
  </Dial>
</Response>

PBXからは、URIをSIP宛先としてダイヤルします。ユーザー名やパスワードは不要です。トークンが認証情報となるため、使用されるまでURIはパスワードと同様に扱ってください。

SIP エンドポイント（永続アドレス）

1. エンドポイントを作成する

curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Main PBX"}'
{
  "id": 7,
  "name": "Main PBX",
  "agent_id": 12,
  "sip_uri": "sip:agent-12-jhxmginwjx@sip.thunderphone.com",
  "username": "tp409667538f83",
  "password": "8mJ0…",
  "allowed_source_cidrs": [],
  "status": "active",
  "created_at": "2026-09-25T21:46:18Z"
}

2. システムの接続先を設定する

次の設定で SIP トランクまたは宛先を構成します。

設定値
SIP URIエンドポイントの sip_uri
ユーザー名 / パスワードusername / password（ダイジェスト認証。ThunderPhone は通話ごとにチャレンジします）
トランスポートポート 5060 の TCP、またはポート 5061 の TLS（推奨）、あるいはポート 5060 の UDP
コーデックG.711（PCMU/PCMA）または G.722

これらのトランスポートおよびコーデック設定は、通話ごとの URI にも適用されます。 どちらの種類のアドレスにも、次の 2 つのネットワーク上の注意点があります。

  • Record-Route に従う。 最初の INVITE の後、通話の残りの シグナリング（ACK、切断、転送）は、応答した特定の ThunderPhone サーバーに送られます。 このサーバーは Record-Route ヘッダー （sip-1.thunderphone.com または sip-2.thunderphone.com、あるいはその IP アドレス） に記載されています。送信 SIP を制限している場合は、sip.thunderphone.com に加えて これらのホストも許可してください: 172.170.39.202（sip）、13.86.104.121 （sip-1）、20.80.98.90（sip-2）。
  • 音声は別の場所に送られる。 sip.thunderphone.com はシグナリングのみを処理します。 SDP 応答内のアドレスおよびポートへのメディア（RTP）を許可してください。

このアドレスへのすべての通話は、そちら側で発信者がどの番号にダイヤルしたかにかかわらず、 エンドポイントのエージェントに届きます。番号をインポートする必要はないため、そちら側で 番号をローテーションしても ThunderPhone 側の変更は不要です。

ダイヤルされた番号を渡す（任意）

発信者がどの番号にダイヤルしたかを記録するには、INVITE 内の X-Original-To ヘッダー（例: X-Original-To: +14155550142）または標準の Diversion ヘッダーで送信します。ThunderPhone はこれを通話の宛先として保存します。

宛先は次の順序で選択されます。通話ごとの URI の登録時に指定した to_number、次に X-Original-To 内の番号、次に Diversion 内の番号です。いずれにも番号がない場合、 エンドポイントでは sip:agent-12-jhxmginwjx（エンドポイントのアドレス）、通話ごとの URI では sip:call と表示されます。

Twilio では、SIP URI にヘッダーを追加できます。 sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tcp?X-Original-To=%2B14155550142。

送信元 IP を制限する（任意）

ユーザー名とパスワードに加えて、allowed_source_cidrs を設定し、自システムの シグナリングアドレスからの通話のみを受け付けます。

curl -X PATCH https://api.thunderphone.com/v1/sip-endpoints/7 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_source_cidrs": ["203.0.113.0/28"]}'

他のアドレスからの通話は、エージェントに到達する前に拒否されます。メディア用アドレス ではなく、システムが SIP シグナリングの送信元として使用するアドレスを指定してください （Twilio などの通信事業者の場合は、公開されているシグナリング IP 範囲）。

発信者とシステムに表示される内容

  • 発信者番号: From ヘッダーのユーザー部分が発信者として保存されます。電話番号（数字、および任意の +、スペース、ダッシュ、ドット、角かっこ）は E.164 に正規化されます。SIP ユーザー名など、それ以外の値は送信されたまま保持されます。保持されるのは最大 32 文字で、発信者がない場合は anonymous として保存されます。
  • 拒否された通話: 不明または期限切れの通話ごとの URI には SIP 404 Not Found が返されます。すでに使用された通話ごとの URI、無効化されたエンドポイント、または許可リスト外の送信元（許可リストを設定したエンドポイントへの UDP 通話を含む）は、エージェントの開始前に切断されます。システム上では通話失敗として表示されるか、接続後すぐに終了する場合があります。これらの拒否は通話履歴エントリーを作成しません。組織のクレジットが不足しているか、支出上限に達している場合、通話は拒否され、通話履歴には料金なしの失敗した通話として表示されます。通話ごとの試行を再実行するには、新しい URI を登録してください。
  • 転送: エージェントのコールド転送は機能します（ThunderPhone が SIP REFER を送信し、システム側でこれを受け入れる必要があります）。SIP アドレス通話では、2 番目のレッグの発信者番号として表示する ThunderPhone 番号がないため、ウォーム転送は利用できません。Twilio では、上記の TwiML はエージェントを接続しますが、転送は処理しません。<Dial> に referUrl="https://YOUR_SERVER/sip-transfer" を追加し、その webhook で ReferTransferTarget を読み取り、転送先に発信する TwiML を返してください（Twilio の SIP REFER ガイドを参照）。
  • テキストメッセージ: SIP アドレスとダイヤルされた番号ではテキストメッセージを送信できません。エージェントが SIP アドレス通話中にテキストメッセージを送信できるのは、テキスト送信用に別途 SMS 対応番号が設定されている場合のみです。それ以外の場合、SMS ツールは利用できません。
  • 登録: ThunderPhone は SIP REGISTER を受け付けません。アドレスに通話を送信し、登録は行わないでください。

料金

SIP アドレス通話には、エージェントの通常の分単位料金が適用されます。ThunderPhone 番号が通話を扱わないため、電話番号料金はかかりません。通信事業者側の通話料金は通常どおり請求されます。料金を参照してください。

テストする

  1. 上記の説明に従って、通話ごとの URI またはエンドポイントを作成します。
  2. システムから、または任意の SIP ソフトフォンからダイヤルします（エンドポイントの場合は、ユーザー名とパスワードを入力します）。
  3. 通話を終了した後、ダッシュボードの 通話 で通話を開くか、GET /v1/calls/{call_id} で取得します。発信者、宛先（「ダイヤルされた番号を渡す」の順序を参照）、文字起こしが表示されます。

API の詳細: SIP アドレス API リファレンス。