SMS API 常见问题

安装 SDK 并发送到指定的测试接收号码 +15005550006，大约五分钟即可完成。您甚至可以在配置号码之前就发布 CI 检查。

一个发送端点、双向入站消息、号码配置（长号码、短号码、免费电话号码和字母数字发送者 ID）、A2P 10DLC 和退订合规、直连运营商路由以及送达分析——全部集成在一个 API 中。

Bird 通过 240 多条直连运营商线路覆盖 150 多个国家，当运营商路径质量下降时可进行电信级路由重选。

如果要向美国号码发送应用到个人的短信，是的。品牌和活动注册可在控制台中完成，状态可通过 API 查询。

按条计费，费率取决于目的地国家/地区和您使用的发送者类型，因此美国长码和英国字母数字发送者 ID 的价格是分开的。各国费率已在 SMS 定价页面上公布。

会。计费按分段而非按条。一个分段可容纳 160 个 GSM-7 字符，但只要包含一个表情符号或非拉丁字符，整条消息就会切换为 Unicode 编码，此时一个分段仅容纳 70 个字符。较长的文本会被拆分，每个分段都会计费，因此一个多余的字符可能使大规模营销活动的成本翻倍。

运营商费用按条收取，因目的地和运营商而异。在美国，10DLC 还涉及品牌和活动注册费。两者均列在 SMS 运营商费用页面上。

SMS 日志在每条消息计价后会显示其分段数和费用；SMS 指标面板会汇总一段时间内的接受量、分段数和支出。

GSM-7 编码的消息每个分段可容纳 160 个字符；切换到 Unicode（UCS-2）以支持表情符号或非拉丁文字时，每段降至 70 个字符。较长的消息会跨分段拼接，SDK 会在发送前报告分段数。

最多 12 个分段，大约相当于 1,836 个 GSM-7 字符或 804 个 Unicode 字符。Bird 绝不会截断消息：超出上限的内容会返回 422 错误。限制以分段而非字符计数，正是因为两种编码方式每段容纳的字符数不同。

批量调用最多 100 条，每条可设置独立的接收者和内容。单条消息只发送给一个接收者，因此批量调用是实现群发的方式。

免费版密钥每分钟可进行 10 次单条发送和 5 次批量调用，付费计划会提高两者的上限。每个响应都带有 IETF RateLimit 头部，告诉您剩余配额和窗口重置时间，建议据此调节发送节奏，而非依赖硬编码数值。

这由运营商决定，而非 Bird。已注册的 10DLC 长号码的吞吐量取决于品牌信任分数和活动类型：高于未注册号码，低于短号码。短号码可获得最高且最稳定的速率。

对于美国应用流量，10DLC 长码可覆盖大多数双向通信和 OTP 用例。大批量一对多项目可转为短码；免费电话号码是美国/加拿大无需 10DLC 的另一选择。

长码或免费电话号码可即时获取，注册或验证通过后即可开始发送。短码需经运营商审核，通常需要数周时间。

可以。长码、短码和免费电话号码均支持双向通信：将号码的入站流量指向一个 webhook，回复会以签名事件的形式送达。字母数字发送者 ID 仅支持单向发送。

取决于发送者类型和国家/地区。美国应用流量需要 A2P 10DLC，免费电话号码需要验证，许多国家/地区要求预先注册发送者 ID——所有这些都可在控制台中完成。

它是一个短文本字符串，通常是您的品牌名称，显示在收件人的

尽量简短：GSM 网络通常最多支持 11 个字符。具体限制取决于目标国家和运营商，以及各方所接受的规则。

免费号码是 8xx 号码（800、888、877 及其他免费前缀），可在美国和加拿大发送和接收 SMS。通过免费号码验证后，即可承载应用流量，无需 A2P 10DLC。

不需要。免费号码不属于 A2P 10DLC 体系，而是通过免费号码验证，运营商在允许该号码满量发送之前会审核用途和消息内容。

10 位长号码（10DLC）是一种标准的本地电话号码，在完成品牌和活动的运营商注册后，可用于在美国发送应用到个人的 SMS。

已注册的 10DLC 长号码可获得经审核的吞吐量，具体取决于品牌信任分数和活动类型：高于未注册号码，低于短号码。

短代码是经运营商批准用于大批量一对多 SMS 的 5–6 位数号码：营销活动、提醒和高频 OTP。它是吞吐量最高的发送方类型，在发送前需通过运营商审核。

请以周为单位规划，而非分钟。运营商会在短代码上线前审核每个短代码项目，因此短代码有实际的准备周期，不像长代码那样注册通过后即可购买并立即开始发送。

专用短代码为您独享，发送信誉完全由您自己掌控。共享短代码通过关键词在多个发送方之间共用同一号码：更便宜、启用更快，但您会继承该号码上其他所有发送方的信誉。

由您选择。在自由文本发送中：传入您工作区拥有的号码、短代码或目的地国家/地区允许的字母数字发送方 ID。如果不传入，发送将被拒绝，而非由系统猜测。模板发送是例外，因为它会自动选择发送方。

它告知 Bird 和运营商您发送的原因，各国/地区的合规规则（如退订策略和静默时段）也基于此类别。自由文本发送必须指定类别；模板发送则继承模板自身的分类。

传入幂等性密钥后，重试请求将返回原始结果，而不会重复发送。如果不传入，重试将被视为一条新消息。

每次状态变更都会触发一个经 HMAC 签名的 Webhook（排队中、已发送、已送达或失败），携带运营商送达回执和分段计数。

每条发送到您已开通号码的消息都会以经 HMAC 签名的 sms.received Webhook 到达。您验证一个签名，读取 from、to 和 text，然后路由到您自己的逻辑中——与您已处理的送达回执格式相同。

可以。从消息接收的同一号码回复即可。将 from 设为您的号码，to 设为原始发送方，对话就会始终在同一号码上进行。

Bird adds the sender to your suppression list and fires sms_suppression.created, and blocks later sends from that sender to that number automatically. HELP returns a help reply and START opts them back in, all handled before they reach your code, so you stay compliant without writing the keyword logic yourself.

您需要支持双向通信的号码。长号码、短号码和免费号码支持接收消息；字母数字发送者 ID 仅支持发送，无法接收回复。

您的消息通过我们 240 多条直连链路直接传递给移动运营商，而非经过层层转售商。跳数越少，消息滞留或投递回执丢失的风险就越低。

Bird 会实时重新选择路由。如果某条路径开始丢失回执或速度变慢，下一条消息会通过更健康的连接到达同一运营商，您编写的发送代码无需任何更改。

每条消息都会返回运营商投递回执，以 sms.delivered 或 sms.failed webhook 的形式送达，包含 mcc_mnc、country 和 latency_ms。这是运营商自身的确认，而非我们的推测。

会。我们在每次发送时都会进行 MNP 查询，以确定收件人当前的运营商，因此携号转网的号码会路由到实际持有该号码的运营商。如需独立的号码情报服务，请参阅 Lookup。

路由会根据目的地在成本和投递质量之间取得平衡。一次性验证码等事务性流量优先选择最高质量路径；批量流量可倾向于最低成本。选择在每条消息级别进行，使用同一个 API 调用。

来自运营商针对每次发送返回的送达回执（DLR）。Bird 将回执与消息关联记录，然后将这些回执汇总为送达率、失败率和延迟指标。送达计数是运营商确认接收，而非 Bird 的推测。

Yes, from its own endpoint. The stats API has one breakdown per dimension (carrier, country, originator, category, status, error code, tag) plus daily and hourly series, and each row carries the one dimension you asked for. Crossing two of them, such as a carrier inside a country, means two calls and joining the rows yourself. A failure rate that looks fine nationally often turns out to be one carrier rejecting one sender ID.

两种方式都支持。每个送达状态已通过 webhook 推送，因此您可以基于事件流构建自己的数据存储。当您希望由 Bird 来完成聚合而不是自己维护计数器时，可以使用统计 API。

将消息 ID 传入事件端点，即可获取其完整时间线：排队、已发送、已送达或失败，每个状态都带有时间戳，失败时还附带运营商原因代码。当客户说没收到短信时，这就是您真正需要的报告。

可以。退订是可逆的。收件人发送 START 即可从屏蔽列表中移除，并重新接收消息。选择权始终在收件人手中。

屏蔽列表是可查询的 API 资源。在构建受众之前查询号码，确保已退订的收件人不会重新进入发送列表。

取决于您发送的目的地和内容。美国的应用类短信需要完成 A2P 10DLC 品牌和活动注册。许多国家要求字母数字发送者预先注册发送者 ID。退订处理适用于所有地区，无需额外设置。

Bird 向运营商或注册机构提交每项注册，并通过 API 报告其状态。您的代码可以轮询注册状态并等待批准，而不是向尚未生效的活动发送消息。

不是。它与发送、号码管理和双向通信使用相同的客户端和密钥。注册状态和退订名单与发送接口一样都是 API 资源，因此一次集成即可覆盖发送和相关合规规则。

为了遏制发送方伪造，许多国家/地区只投递已在当地运营商或监管机构预注册的字母数字发送方 ID。在适用该规则的地区，未注册的品牌发送方会被拒绝或改写。

Bird 来处理。您在控制台中提交发送方 ID 和目的地，Bird 将其提交到当地注册机构，API 会报告其状态，以便您了解发送方何时上线。

审批需经过外部运营商和注册机构，因国家/地区而异，通常需要数天到数周。通过 API 轮询注册状态，等待审批通过后再使用该发送方 ID 发送。

A2P 10DLC 是美国运营商针对通过标准 10 位长代码发送的应用到个人 SMS 的框架。企业需注册其流量背后的品牌以及描述消息内容的活动，运营商在授予吞吐量之前会对两者进行审核。

品牌是发送流量的法律实体。活动描述该品牌下的特定消息用途。一个品牌可以有多个活动，您将号码关联到活动而非品牌。

品牌和活动审核需经过运营商和注册机构，通常需要数天到数周。通过 API 查询活动状态，让您的代码在审批通过后再发送。

不适用。10DLC 是美国框架。其他国家/地区有各自的规则，许多国家/地区要求预注册发送方 ID，无论您在哪里发送，退订关键词处理都适用。

您对 Bird 的调用通过 HTTPS 加密，我们发送给您的入站 webhook 同样如此。最后一跳不在我们的加密范围内：SMS 是一种运营商协议，没有端到端加密，消息在手机上和运营商处均可读取。因此，请勿在消息正文中包含敏感信息，对于任何敏感内容建议使用 WhatsApp 或电子邮件。

每个事件都经过 HMAC 签名。在处理 payload 之前，请使用您端点的密钥验证签名，并可随时在控制台中轮换该密钥。

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

仅限于您赋予的权限范围。密钥包含一组作用域，每个作用域分为读取或写入权限，因此一个用于发送 SMS 的密钥无法管理您的号码或读取其他通道。管理成员和签发密钥等控制面操作仅限控制台，任何密钥都无法触及。

两者都可以。密钥支持设置 CIDR 范围白名单，拒绝来自其他地址的请求；轮换时旧密钥会在宽限期内继续有效（默认 24 小时，或设为零立即失效），因此轮换无需停机。

有。审计日志是只读的组织级记录，涵盖每一项管理操作，包括操作者、工作区、时间和结果，并支持导出为 OCSF 格式以供您的 SIEM 使用。

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