透過 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 僅可用於一通通話： 通話一旦使用過它，即使該通話很快結束，它也會失效。

例如，使用 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 可連接智慧體，但不會處理轉接：請將 referUrl="https://YOUR_SERVER/sip-transfer" 加入 <Dial>，並讓 該 Webhook 讀取 ReferTransferTarget，然後回傳撥打轉接目的地的 TwiML（請參閱 Twilio 的 SIP REFER 指南）。
• 簡訊：SIP 位址和撥打的號碼無法傳送簡訊。只有在智慧體已設定 可傳送簡訊的獨立 SMS 號碼時，才能在 SIP 位址通話期間傳送簡訊； 否則其 SMS 工具無法使用。
• 註冊：ThunderPhone 不接受 SIP REGISTER。請將通話傳送至該 位址；請勿向該位址註冊。

定價#

SIP 位址通話依智慧體的一般每分鐘費率計費。由於沒有 ThunderPhone 號碼承載通話，因此不收取電話號碼費用。你的電信業者仍會如常針對其 通話端計費。請參閱 定價。

測試#

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

API 詳細資訊：SIP 位址 API 參考文件。