--- 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 摘要驗證使用者名稱與密碼（也可選擇設定來源 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}}`，方式與[撥出通話](/zh-Hant/guides/call-variables)相同。 - `call_id` 是通話連線後在通話紀錄中使用的 ID （`GET /v1/calls/{call_id}`）。 ### 2. 撥打 URI 請在 5 分鐘內將通話傳送至 `sip_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 號碼承載通話，因此不收取電話號碼費用。你的電信業者仍會如常針對其 通話端計費。請參閱 [定價](/zh-Hant/guides/pricing)。 ## 測試 1. 如上所述建立單次通話 URI 或端點。 2. 從你的系統或任何 SIP 軟體電話撥打該 URI（若為端點，請輸入 使用者名稱和密碼）。 3. 掛斷後，在控制台的 **通話** 中開啟該通話，或使用 `GET /v1/calls/{call_id}` 擷取。內容會顯示來電者、目的地 （請參閱「傳遞撥打的號碼」下方的順序）以及逐字稿。 API 詳細資訊：[SIP 位址 API 參考文件](/api-reference/sip-addresses)。