透過 SIP 連接（無需電話號碼）

透過每次通話使用一次性 SIP URI 或固定 SIP 地址，直接由你的 PBX、電訊商或 SIP 應用程式將通話轉接至 ThunderPhone 智能體。

如果你自有系統已處理電話號碼（例如 PBX、聯絡中心平台，或會輪換號碼的電訊商帳戶），你可以透過標準 SIP 將通話傳送至 ThunderPhone 智能體。你無需在 ThunderPhone 匯入或購買號碼。你的系統只需撥打 SIP 地址，智能體便會接聽。

SIP 地址分為兩種：

兩種類型均會路由至你組織中的同一個智能體，並會如其他來電一樣顯示在通話記錄中。

每次通話 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 是通話接通後在通話記錄中顯示的 ID（GET /v1/calls/{call_id}）。

2. 撥打 URI#

請在 5 分鐘內將通話傳送至 sip_uri。此 URI 僅適用於一次通話：一旦有通話使用過，即使該通話很快結束，URI 亦會失效。

例如使用 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 中繼或目的地：

這些傳輸協定及編解碼器設定同樣適用於每通通話 URI。兩項網絡細節對兩種地址均很重要：

• 遵循 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 只承載信令。請允許 RTP 媒體傳送至 SDP 回應中的地址及連接埠。

無論來電者在你的系統一方撥打哪個號碼，每通撥打至此地址的通話均會到達端點的智能體。你無需匯入號碼，因此在你的系統一方輪換號碼時，無需在 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 位址通話不支援熱轉接，因為沒有 ThunderPhone 號碼可在第二段通話中顯示為來電顯示。使用 Twilio 時，上述 TwiML 可連接智能體，但不會處理轉接：請在 <Dial> 加入 referUrl="https://YOUR_SERVER/sip-transfer"，並讓該 webhook 讀取 ReferTransferTarget，然後傳回撥打轉接目的地的 TwiML（請參閱 Twilio 的 SIP REFER 指南）。
• 文字訊息：SIP 位址及已撥號碼均不能發送短訊。只有當智能體已設定另一個可發送 SMS 的號碼作短訊用途時，才可在 SIP 位址通話期間發送短訊；否則其 SMS 工具將無法使用。
• 註冊：ThunderPhone 不接受 SIP REGISTER。請將通話傳送至該位址；不要向其註冊。

收費#

SIP 位址通話會按智能體的一般每分鐘費率計費。由於沒有 ThunderPhone 號碼承載通話，因此不收取電話號碼費用。你的電訊服務供應商會照常就其部分通話收費。請參閱 收費。

測試方法#

1. 按上述方式建立每次通話 URI 或端點。
2. 從你的系統或任何 SIP 軟電話撥打該位址（如使用端點，請輸入使用者名稱及密碼）。
3. 掛線後，在控制台的 通話 開啟該通話，或使用 GET /v1/calls/{call_id} 擷取。內容會顯示來電者、目的地（請參閱「傳遞已撥號碼」下的順序）及逐字稿。

API 詳情：SIP 位址 API 參考資料。