--- title: "透過 SIP 連接（無需電話號碼）" description: "透過每次通話使用一次性 SIP URI 或固定 SIP 地址，直接由你的 PBX、電訊商或 SIP 應用程式將通話轉接至 ThunderPhone 智能體。" --- 如果你自有系統已處理電話號碼（例如 PBX、聯絡中心平台，或會輪換號碼的電訊商帳戶），你可以透過標準 SIP 將通話傳送至 ThunderPhone 智能體。你無需在 ThunderPhone 匯入或購買號碼。你的系統只需撥打 SIP 地址，智能體便會接聽。 SIP 地址分為兩種： | | **每次通話 SIP URI** | **SIP 端點** | |---|---|---| | 格式示例 | `sip:c-@sip.thunderphone.com` | `sip:agent--@sip.thunderphone.com` | | 建立方式 | 每次通話一次 `POST /v1/calls/register-sip` | 一次 `POST /v1/sip-endpoints` | | 驗證方式 | 地址中的一次性權杖 | SIP Digest 使用者名稱 + 密碼（以及可選的來源 IP 允許清單） | | 適用情況 | 在轉接通話前已呼叫 API 的應用程式；每次通話變數 | 只需將「中繼線路指向」ThunderPhone 的 PBX 及電訊商 | | 有效期 | 5 分鐘，僅限一次通話 | 直至你刪除為止 | 兩種類型均會路由至你組織中的同一個智能體，並會如其他來電一樣顯示在通話記錄中。 ## 每次通話 SIP URI ### 1. 登記通話 ```bash 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"} }' ``` ```json { "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}}`，方式與[外撥通話](/yue/guides/call-variables)相同。 - `call_id` 是通話接通後在通話記錄中顯示的 ID（`GET /v1/calls/{call_id}`）。 ### 2. 撥打 URI 請在 5 分鐘內將通話傳送至 `sip_uri`。此 URI 僅適用於一次通話：一旦有通話使用過，即使該通話很快結束，URI 亦會失效。 例如使用 Twilio 時，請為你要轉交的通話回傳以下 TwiML： ```xml sip:c-1790372992.Qm3xT8vLk2PzR7nYw4HbJa.uF6sD1gK9eW2cX5vB8nM0q@sip.thunderphone.com;transport=tcp ``` 如使用 PBX，請將 URI 作為 SIP 目的地撥打。無需使用者名稱或密碼；權杖即為憑證，因此在 URI 被使用前，請像保護密碼一樣保護它。 ## SIP 端點（永久地址） ### 1. 建立端點 ```bash 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"}' ``` ```json { "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" } ``` `password` 只會在建立端點時傳回一次。請立即將其儲存於你的 PBX 或電訊供應商設定中。如遺失密碼，請使用 `POST /v1/sip-endpoints/{id}/rotate-password` 輪換密碼。 ### 2. 將你的系統指向端點 使用以下設定配置 SIP 中繼或目的地： | 設定 | 值 | |---|---| | SIP URI | 端點的 `sip_uri` | | 用戶名稱／密碼 | `username` ／ `password`（摘要驗證；ThunderPhone 會對每通來電發出驗證要求） | | 傳輸協定 | 連接埠 5060 的 TCP、連接埠 5061 的 TLS（建議），或連接埠 5060 的 UDP | | 編解碼器 | G.711（PCMU/PCMA）或 G.722 | 優先使用 TCP 或 TLS。UDP 可從公開地址及大多數 NAT 運作，但如位於「對稱式」NAT 後方（即每個目的地均使用新連接埠的 NAT），智能體的掛線及轉接可能無法送達你的系統。來源 IP 允許清單（見下文）亦需要使用 TCP 或 TLS。透過 TLS，SIP 信令在經過 `sip.thunderphone.com` 後仍會保持加密，直至處理通話的伺服器。 這些傳輸協定及編解碼器設定同樣適用於每通通話 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`，在用戶名稱及密碼以外，只接受來自你自身信令地址的通話： ```bash 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 範圍），而非你的媒體地址。 允許清單只會檢查透過 TCP 或 TLS 的通話。UDP 來源地址可以被偽造，因此設有允許清單的端點會拒絕所有透過 UDP 到達的通話。請使用 `;transport=tcp`（連接埠 5060）或 TLS（連接埠 5061）向該端點傳送通話。 ## 來電者及你的系統所見內容 - **來電顯示**：`From` 標頭的使用者部分會儲存為來電者。 電話號碼（數字，可選擇包含 `+`、空格、連字號、句點或括號）會正規化為 E.164；其他內容（例如 SIP 使用者名稱）則會按原樣保留。最多保留 32 個字元；如沒有來電者，則儲存為 `anonymous`。 - **被拒絕的通話**：未知或已過期的每次通話 URI 會收到 SIP `404 Not Found`。已使用的每次通話 URI、已停用的端點，或不在允許清單內的來源（包括任何撥打設有允許清單端點的 UDP 通話），都會在智能體啟動前中斷：你的系統可能會顯示通話失敗，或先接通後立即結束。這些拒絕不會建立通話記錄。如你的機構餘額不足或已達支出上限，通話會被拒絕，並在通話記錄中顯示為未收費的失敗通話。如要重試每次通話的嘗試，請建立新的 URI。 - **轉接**：智能體的冷轉接可正常運作（ThunderPhone 會傳送 SIP `REFER`，你的系統必須接受）。SIP 位址通話不支援熱轉接，因為沒有 ThunderPhone 號碼可在第二段通話中顯示為來電顯示。使用 Twilio 時，上述 TwiML 可連接智能體，但不會處理轉接：請在 `` 加入 `referUrl="https://YOUR_SERVER/sip-transfer"`，並讓該 webhook 讀取 `ReferTransferTarget`，然後傳回撥打轉接目的地的 TwiML（請參閱 Twilio 的 [SIP REFER 指南](https://www.twilio.com/docs/voice/api/refer-to-twilio)）。 - **文字訊息**：SIP 位址及已撥號碼均不能發送短訊。只有當智能體已設定另一個可發送 SMS 的號碼作短訊用途時，才可在 SIP 位址通話期間發送短訊；否則其 SMS 工具將無法使用。 - **註冊**：ThunderPhone 不接受 SIP `REGISTER`。請將通話傳送至該位址；不要向其註冊。 ## 收費 SIP 位址通話會按智能體的一般每分鐘費率計費。由於沒有 ThunderPhone 號碼承載通話，因此不收取電話號碼費用。你的電訊服務供應商會照常就其部分通話收費。請參閱 [收費](/yue/guides/pricing)。 ## 測試方法 1. 按上述方式建立每次通話 URI 或端點。 2. 從你的系統或任何 SIP 軟電話撥打該位址（如使用端點，請輸入使用者名稱及密碼）。 3. 掛線後，在控制台的 **通話** 開啟該通話，或使用 `GET /v1/calls/{call_id}` 擷取。內容會顯示來電者、目的地（請參閱「傳遞已撥號碼」下的順序）及逐字稿。 API 詳情：[SIP 位址 API 參考資料](/api-reference/sip-addresses)。