语音 API 常见问题

Bird Voice 允许您通过 SIP 中继向电话号码拨打电话。您的电话系统连接到 Bird，Bird 通过运营商将每通电话路由到公共电话网络（PSTN）。您使用自己的 PBX 或软电话；Bird 负责处理运营商链路。

大约十分钟。创建一个 SIP 中继，验证主叫号码，启用目的地国家，然后将您的电话系统指向中继地址。首次通话指南会引导您完成整个流程。

您需要准备三样东西：一个允许您的设备接入的 SIP 中继（通过 IP 范围或 API 密钥授权）、一个已验证的主叫号码（您作为来电方显示的号码），以及已启用的目的地国家。Bird 会将路由附加到您的工作区，这是第四个前提条件，由 Bird 完成。

不需要。任何支持 SIP 的电话系统均可使用：笔记本电脑上的 Zoiper 或 Linphone 等软电话、Asterisk 或 FreeSWITCH 等 PBX，或 3CX、FreePBX 等商用系统。Bird 会为您分配一个 SIP 域名，您将设备指向该域名即可。

Yes. You can place calls from the dashboard Phone app using WebRTC.

按通话计费，费率取决于目的地国家。每个费率有一个计费增量：最低计费时长，以及之后的进位步长。例如，一个最低计费一分钟、步长为六秒的费率，会将一通 10 秒的通话按整分钟计费。

计费时间从被叫方接听起算，到通话结束为止。振铃时间不计费，因此无人接听的通话不产生费用。

预付费，从您组织的钱包中扣款。Bird 在拨通运营商之前会检查您的余额，因此余额不足的通话会在拨出前以 insufficient_balance 原因被拒绝，而非事后计费。

是的。每个组织有每日语音消费上限，在每个 UTC 日开始时重置。超过限额后，通话将被拒绝并返回 daily_spend_exceeded。具体金额取决于您的套餐，Bird 可以根据请求提高限额。

在通话记录中打开该通话。费用在计费完成后显示在记录上，精确到完整精度，不含税。如需查看多个通话的总费用，可从通话页面将筛选后的通话列表导出为 CSV，或查看您的发票和使用情况。

三个上限：同时进行的通话数（并发通话数）、每秒可发起的新通话数（每秒通话数），以及 UTC 日内语音消费上限（每日消费限额）。每项限制按组织设定，具体额度取决于您的套餐。

通话在建立阶段即被拒绝，运营商不会被拨通。通话记录会标明触发了哪个限制：concurrent_calls_exceeded、calls_per_second_exceeded 或 daily_spend_exceeded。您的电话系统会收到 SIP 503 响应。

可以。联系支持团队申请更高的并发通话数或每秒通话数上限。每日消费上限取决于您的套餐，也可以提高。

请查看通话记录中的拒绝原因。拨号器可能在远未达到并发通话上限时就触发了 calls_per_second_exceeded，因为这两个限制是独立的。降低拨号速率后重试；立即重试会得到相同的结果。

SIP 中继是您的电话系统与 Bird 之间的连接。SIP（会话发起协议）是电话系统用于建立通话的协议，中继是通话传输的线路。Bird 会为您的工作区分配一个中继地址，您只需将电话系统指向该地址即可。

大多数工作区只需要一个。当您需要为不同站点或系统设置独立的访问规则时，可以创建更多中继，因为 IP 允许列表、允许的 API 密钥和 Digest 设置都是按中继配置的。

中继的 SIP 域名（从中继页面复制）、用户名 bird，以及密码（即该中继上已授权的 API 密钥的密钥值）。将呼叫发送到 SIP 域名的端口 5060（UDP 或 TCP）或 5061（TLS）。

可以，通过 IP 允许列表、允许的 API 密钥或两者结合。添加您设备发送 SIP 的公共地址，或要求每个通话通过 SIP Digest 使用 API 密钥进行身份验证。两者都在下一次通话时生效。

中继的 SIP 域名会立即停止接受新通话。正在进行的通话将继续，通过该中继产生的通话记录仍保留在您的通话日志中。

您的 PBX 发送呼叫，Bird 以 407 质询响应，然后您的 PBX 使用 Proxy-Authorization 头重新发送呼叫，该头由用户名 bird 和您的 API 密钥的密码计算得出。您的 PBX 发送的是密码的哈希值，而非密码本身。

SHA-256 和 MD5。Bird 默认优先提供 SHA-256，其次是 MD5，您的 PBX 会选择其支持的第一个算法。如果您的设备仅支持 MD5，且无法正确处理以 SHA-256 开头的质询，请将中继设置为仅 MD5。

可以。当中继同时配置了两者时，Bird 会在质询密码之前先检查源地址，因此来自未列入白名单地址的呼叫无论携带什么凭据都会被拒绝。

先将新密钥添加到中继，再将您的设备切换过来，然后撤销旧密钥。撤销或删除密钥会立即移除其在所有允许该密钥的中继上的认证能力。

来电显示号码是您的工作区被允许在外呼中作为主叫方显示的电话号码。Bird 会在每次呼叫时将您设备放入 SIP From 头中的主叫号码与此列表进行核对，因此呼叫只能使用您已验证的号码外拨。

在号码页面以 E.164 格式添加号码。Bird 会立即拨打验证电话。接听电话，听取六位数验证码，然后在控制面板中输入。您有五次尝试机会，只要有一次验证成功，该号码即可使用。

如果尝试次数已用完，请点击该号码所在行的

在验证所需的那一分钟内，将该号码转接到您可以接听的电话上，验证完成后再转回。如果该号码完全不接收来电，请联系支持团队。

从那一刻起，任何使用该号码的呼叫都会被拒绝，原因为 caller_id_not_verified。已在进行中的呼叫不受影响，使用过该号码的通话记录也保持不变。

话费欺诈的手段是拨打您从未打算呼叫的高费率国家/地区。您启用的国家/地区就是您可能产生费用的范围，因此关闭其他所有国家/地区可以在有人入侵您的电话系统时限制您的风险敞口。

在目的地页面使用搜索框查找国家/地区（支持按名称或两位字母代码搜索），然后开启其开关。更改即时生效。

拨打高风险国家/地区的费用很高，而您所拨号码的运营者会从中获取一部分费用。这些正是攻击者在入侵电话系统后会瞄准的国家/地区。除非您在当地有业务需求，否则请保持关闭状态，并在启用前查看费率。

请联系支持团队为您的账户开通。Available 表示您可以启用；Not supported 表示 Bird 目前无法从您的账户向该国家/地区拨打电话。

已启用的国家/地区内仍可能存在路由尚未覆盖的特定目的地。请将呼叫 ID 发送给支持团队，他们会扩展路由以覆盖该目的地。

两个头字段：To（被叫号码）和 From（您作为来电方显示的号码，必须是已验证的主叫号码）。两者都必须是 E.164 格式的完整国际号码，即以 + 开头，后跟国家代码和国内号码。无需自定义头字段。

STIR/SHAKEN 是运营商在决定是否让通话不加标记地接通时使用的签名机制。拨打美国和法国的电话会自动携带该签名，无需您进行任何配置。默认携带 B 级签名；如需 A 级（最高级别），可申请开通。

在通话日志中打开该通话。您的电话系统只会看到一个普通的 SIP 503，但具体原因会记录在只有您能查看的通话记录中。详情上方的面板会标明原因并链接到相应的修复设置。

只有在原因消除后才应重试。因 calls_per_second_exceeded 被拒绝的通话，在您降低拨号速率之前重试会得到相同的结果。请先查看拒绝原因再决定是否重试。

五种：Answered（被叫号码已接听）、No answer（振铃超时无人接听）、Failed（呼叫未完成，可能是 Bird 拒绝了呼叫或运营商处理失败）、Rejected（运营商直接拒绝了呼叫）和 Unknown（无法确定结果）。

两者都显示为 Failed。区分它们的是拒绝原因：只有 Bird 拒绝才会附带拒绝原因。带有拒绝原因的失败呼叫指向您或 Bird 一方的设置问题；没有拒绝原因的失败呼叫通常指向您所拨打的号码。

可以。呼叫页面的实时标签页会列出您中继上当前的所有呼叫及其数量。正在进行的呼叫显示为 Ringing（等待对方接听）或 In progress（已接通）。该标签页每隔几秒自动刷新。

总时长从 Bird 收到呼叫开始计算，直到挂断。计费时长从接听开始计算，直到挂断。两者之间的差值是无人接听的振铃时间，因此差值较大时值得检查您拨打的内容。无人接听的呼叫不产生费用。

三种方式：从呼叫页面下载 CSV（导出与当前筛选条件匹配的所有记录，而非仅当前可见页面）；通过 API 使用具有 voice:read 权限的 API 密钥读取；或使用 Bird CLI 执行 bird voice list 命令。

三种：voice_call.initiated（Bird 已接受呼叫并开始路由）、voice_call.answered（被叫号码已接听）和 voice_call.ended（呼叫结束，附带结果）。未被接听的呼叫不会触发 answered 事件。

Bird 在接受 INVITE 后拒绝的通话仍会以 voice_call.ended 结束，携带 failed 状态和 sip_response_code 503。因此，您收到的每个通话开始事件都有对应的结束事件。而 Bird 完全无法接入的通话（在 SIP 层被拒绝）不会产生任何事件。

是的。事件的传递不保证顺序，因此 answered 可能在 ended 之后到达。请按 timestamp 字段排序，并在后到达但时间戳更早的事件冲突时以先到达的为准。

通过 webhook-id HTTP 头进行去重。Bird 至少投递一次，当信令重试重放时，通话的 initiated 事件可能会被多次发布。相同通话、相同阶段、相同 webhook-id。

它们在通话记录中，而非事件中。voice_call.ended 上的 failed 状态不会告诉您是 Bird 还是运营商导致了失败。请在通话日志中打开该通话查看拒绝原因，费用会在通话计费完成后显示。

Bird 无法接入的通话会在 SIP 层被拒绝，此时尚未生成记录。请检查以下四项：中继已设置允许您设备的 IP 范围或 API 密钥；通话来自中继 IP 允许列表中的地址（在 NAT 后面，该地址是路由器的公共地址）；Digest 凭证正确（用户名 bird、正确的 API 密钥值、中继提供的算法）；SIP 域名与中继的域名完全匹配。

在通话记录中打开该通话。详细信息上方的面板会显示原因，并链接到可修复问题的设置。您可以修复的七个原因是：source_not_allowed、caller_id_not_verified、destination_not_enabled、insufficient_balance、daily_spend_exceeded、concurrent_calls_exceeded 和 calls_per_second_exceeded。

某些设备无法正确处理以 SHA-256 开头的挑战。将中继的 Digest 算法设置为仅 MD5，您的 PBX 将收到它能理解的挑战。

您的客户端位于 NAT（会重写地址的路由器或防火墙）后面，媒体流发送到了对方无法到达的私有地址。请开启客户端的 NAT 或 STUN 处理功能，使其在媒体协商中通告公共地址。

可以加密。Bird 支持在端口 5061 上使用 TLS 进行 SIP 信令传输，因此呼叫建立过程在传输中是加密的。端口 5060 上的 UDP 和 TCP 则不加密。请根据您的安全需求选择相应的传输方式。

每个事件都经过 HMAC 签名。在处理负载之前，请使用端点密钥验证签名，并在需要时从控制面板轮换该密钥。

存储在您组织所在的区域，us1 或 eu1。您的 API 密钥前缀中包含区域信息（bk_us1_、bk_eu1_），SDK 和 CLI 据此自动选择正确的端点，无需您额外配置。

仅限于您设定的权限范围。密钥包含一组权限范围，每个范围分为读取或写入。拥有 voice:write 权限的密钥可以在中继上验证通话；拥有 voice:read 权限的密钥可以列出通话记录。密钥无法访问其权限范围之外的频道或设置。

具体原因会记录在通话记录中，只有您才能查看。向 SIP 层返回通用的 503 可以防止探测您中继的人了解到哪些中继、号码和目的地存在。

认证和安全文档位于信任中心 trust.bird.com。数据处理协议、隐私声明和可接受使用政策发布在 bird.com/legal。如需供应商调查问卷，请联系您的 Bird 客户团队处理。