--- 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/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` 仅承载信令。请允许向 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`，仅接受来自您自身信令地址的通话： ```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 地址和所拨号码无法发送短信。只有当智能体已配置一个支持短信的独立号码用于发送短信时，才能在 SIP 地址呼叫期间发送短信；否则其短信工具不可用。 - **注册：** ThunderPhone 不接受 SIP `REGISTER`。请将呼叫发送至该地址；不要向其注册。 ## 定价 SIP 地址呼叫按智能体的常规每分钟费率计费。由于没有 ThunderPhone 电话号码承载该呼叫，因此不收取电话号码费用。您自己的运营商仍会照常对其一侧的呼叫计费。请参阅[定价](/zh/guides/pricing)。 ## 测试 1. 按照上述说明创建单次呼叫 URI 或端点。 2. 从您的系统或任何 SIP 软电话拨打该地址（对于端点，请输入用户名和密码）。 3. 挂断后，在控制台的 **通话** 中打开该呼叫，或使用 `GET /v1/calls/{call_id}` 获取它。其中会显示来电方、目标号码（请参阅“传递所拨号码”下的顺序）和转录文本。 API 详情：[SIP 地址 API 参考](/api-reference/sip-addresses)。