SIP 中继
SIP 中继将您的电话系统连接到 Bird。它为您的 PBX（企业电话交换系统）提供外呼地址，定义 Bird 如何对呼叫进行身份验证，还可以接收您持有号码上的来电。在 Voice > SIP Trunks 下配置中继。
大多数场景只需一个中继。当不同站点或系统需要不同的 IP 允许列表、API 密钥、会话凭据设置或 Digest 算法时，请创建多个中继。
创建中继
点击 Create trunk 并输入名称。此仪表盘标签可以稍后修改，它不会随呼叫发送。
Bird 会为中继分配一个固定的 SIP 域名。将此域名填入您的电话系统，以便 Bird 将呼叫关联到该中继。
新中继默认拒绝所有呼叫，直到您指定谁可以发起呼叫：IP 范围、API 密钥、会话凭据，或它们的组合。
呼叫方向
中继的每个方向独立工作，新建的中继两个方向均未启用。中继页面按方向分区，未启用的方向仅显示开启按钮。
外呼指您的 PBX 通过 Bird 发起呼叫。点击 Enable outbound。未启用前，无论凭据如何，中继都会拒绝所有外呼尝试。中继的连接详情、允许列表、密钥、会话凭据和 Digest 配置都在此区域下，因为它们控制的是谁可以接入。
来电指 Bird 将呼叫投递到您的 PBX，用于该中继应答的号码。点击 Enable inbound，然后至少添加一个投递网关：没有网关的中继会拒绝其号码上的所有来电。该区域的 Inbound numbers 列表显示哪些号码将来电发送到此中继。
将号码指向中继的操作在号码侧完成，而非此处。参见接听来电了解详情，以及网关的号码格式说明。
Warning: turning inbound calling off puts every number pointing at this trunk back on reject, and turning it back on does not restore them. Deleting the trunk does the same.
连接详情
打开一个中继，查看需要在 PBX 中填写的信息：
| 设置 | 值 |
|---|---|
| SIP 域名 | 中继专属域名。从中继页面完整复制 |
| 用户名 | 始终为 bird |
| 密码 | 此中继上允许的 API 密钥的 secret（参见 API 密钥身份验证） |
Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication. A client holding a session credential uses the password from that credential instead.
将呼叫发送到 SIP 域名的以下端口之一：
| 传输协议 | 端口 | 备注 |
|---|---|---|
| UDP | 5060 | 大多数设备默认使用的端口 |
| TCP | 5060 | 与 UDP 相同的端口，在 PBX 上选择传输协议即可 |
| TLS | 5061 | SIP over TLS，用于对信令进行传输加密 |
控制谁可以发起呼叫
中继可通过源 IP 地址、API 密钥或短期会话凭据对设备进行身份验证。根据您的客户端需要启用相应方式。
在 IP allow list、Allowed API keys 和 Session credentials 中进行配置。保存的更改对新呼叫立即生效。
IP 允许列表
添加设备发送 SIP 时使用的公网地址，可以是单个地址或 CIDR 范围，每项可附带可选描述。列表中有一条记录后 IP 过滤即生效：此后只有列出的地址范围才能向此中继发送呼叫。
添加能到达 Bird 的公网源地址。对于 NAT 后面的设备，使用路由器的公网地址而非电话系统的私有地址。Bird 在 SIP 层拒绝来自未列出地址的呼叫，因此这些呼叫通常不会出现在通话记录中。关于呼叫缺失问题，参见语音故障排查。
API 密钥身份验证
Bird 也可以（或同时）要求每次呼叫提供密码。该交换使用 SIP Digest 身份验证：Bird 发送质询，您的电话系统以密码的哈希值（而非密码本身）回应，Bird 根据 Bird API 密钥验证该哈希。
- 为 API 密钥授予 voice 权限并设置为 write 级别，这是中继身份验证所需的级别。可以添加到已有密钥上，也可以新建一个。无论哪种方式，密钥的 secret 都不变：已部署的密钥保留系统中已配置的 secret，新密钥仅在创建时显示一次 secret，请及时保存。参见 API 密钥。
- 在中继页面的 Allowed API keys 下，添加该密钥。
- 在 PBX 中，将用户名设为 bird，密码设为该密钥的 secret。
API 密钥身份验证在列表中有一个密钥后即生效：此后只有列出的密钥才能进行身份验证。
移除密钥上的 voice 权限会立即使其无法通过身份验证，但中继仍将其保留在允许列表中。重新添加该权限后，中继将使用相同的 secret 恢复工作，无需在中继或 PBX 上做任何更改。权限缺失期间，中继页面会标记该密钥，以确保允许列表不会显示为可用状态。
吊销或删除 API 密钥会立即在所有允许该密钥的中继上移除其身份验证能力，且不可恢复。轮换密钥时，先将新密钥添加到中继，再迁移设备，最后吊销旧密钥。
会话凭据
会话凭据是短期有效的 SIP 用户名和密码。它与 API 密钥回应相同的 Digest 质询，但不会暴露长期有效的 secret。
在中继页面的 Session credentials 下开启会话凭据；新中继默认关闭。可以使用会话凭据的场景：
- 仪表盘中的话机，它会为每次呼叫自动生成一个凭据。
- 由 CLI 驱动的 SIP 客户端：bird voice tools test-call 为其发起的呼叫生成凭据，bird voice session-credentials create 生成凭据供粘贴到其他客户端。两者均需 voice 权限且为 write 级别。
凭据归属于工作区而非单个中继，因此客户端可在符合条件的中继间通用。客户端必须出示凭据，且中继必须启用会话凭据。Bird 仅在生成凭据时返回密码。
启用会话凭据不会改变 IP 允许列表中设备的连接方式：来自列出地址的呼叫，在中继没有允许的 API 密钥时，仍无需密码质询即可接入。
Digest 算法
默认情况下，Bird 优先提供 SHA-256，其次提供 MD5。您的 PBX 以其支持的第一个算法作答。
当设备有特殊要求时，在 Digest algorithm 下更改提供的算法。如果 PBX 无法正确处理以 SHA-256 开头的质询，请选择 MD5 only。中继仅接受其提供的算法。API 密钥兼容两种算法，无需重新签发。
在任何通过话机发起呼叫的中继上保留 MD5：浏览器仅支持 MD5，因此仅提供 SHA-256 的中继会拒绝所有浏览器呼叫。
删除中继
删除中继立即生效：其 SIP 域名停止接受新呼叫，指向该中继的所有号码恢复为拒绝来电。已在进行中的呼叫不受影响，通过该中继产生的通话记录保留在通话记录中。
后续步骤
| 页面 | 涵盖内容 |
|---|---|
| 发起第一个呼叫 | 从空白工作区到电话响铃 |
| 话机 | 通过支持会话凭据的中继从仪表盘拨打电话 |
| 发起呼叫 | Bird 在 INVITE 上的要求，以及呼叫费用 |
| 接听来电 | 将号码指向此中继及其投递网关 |
| 主叫号码 | 注册号码并通过验证呼叫证明号码归属 |
| API 密钥 | 创建密钥、选择权限范围和轮换密钥 |