跳到主要内容

如何接入 Twilio 国际短信服务

通过集成 Twilio，您可以为组织开启全球范围内的短信通知与验证码服务。

一、 国际短信使用场景​

在完成 Twilio 对接配置后，当您向非中国大陆号码发送短信时，系统将自动通过 Twilio 通道发出。主要应用场景包括：

  • 在工作流中使用“发送短信”节点，实现全球业务提醒。

  • 开启表单的“号码验证”功能，支持国外手机号实时接收验证码。

  • 外部门户注册登录验证码和邀请、审核结果通知。

二、注册 Twilio 账号​

  1. 打开：https://www.twilio.com
  2. 点击 Sign up 注册账号
  3. 完成邮箱验证与手机验证
  4. 进入控制台（console）：https://console.twilio.com/
关键概念辨析

  • Account SID
    Twilio 账户唯一标识，相当于“账户编号”

  • API Key SID / API Secret
    用于接口调用鉴权

  • Messaging Service SID（MG开头）
    用于发送普通短信（通知类）

  • Verify Service SID（VA开头）
    用于发送和校验验证码短信

  • Sender（发送方）
    可以是手机号或品牌名（Sender ID）

区别总结：

  • Messaging Service → 用于通知、提醒类短信
  • Verify Service → 用于验证码发送与校验（登录/注册）

三、获取 API Key SID 和 Secret​

1. 创建 API Key​

路径： Console → Develop → Go to API Keys → Create API key

注意： Key type 必须选择 Standard。

2. 获取 SID 和 Secret​

API Key 创建完成后，您将获得 SID 和 Secret。

⚠️ 重要提示： API Secret 仅在此处展示一次，请务必妥善保存。若丢失，需重新创建。

四、获取 Messaging Service SID​

  1. 在 Twilio Console 左侧导航栏进入 Messaging → Services。

  2. 点击 Create Messaging Service 按钮，按指引完成创建。

  3. 创建成功后，获取 Messaging Service SID (以 MG 开头)。

注意事项
  • Sender 可以选择手机号、Sender ID（一个字符串形式的标识，例如：YourBrand，会显示在用户手机的“发件人”一栏), 支持选择多个Sender添加到Message Service Sender Pool 中，Twilio会根据接收国等信息智能分配Sender。
  • 添加到 Messaging Service 的发送方（手机号或品牌名）必须已在 Twilio 或本地运营商完成报备（如 10DLC/A2P 等）。
  • 不是所有国家都支持非号码的 Sender ID，部分国家（如中国）只能使用手机号作为 from。
  • 在有报备要求的国家，使用未报备的 Sender 可能导致短信无法发送、被拦截或被用户投诉，建议先完成备案再添加。
  • 在中国等不支持品牌名的地区，只能使用已报备的手机号作为发送方，不要随意添加未审核的号码或 Sender ID。

各国短信发送指导指南：https://www.twilio.com/en-us/guidelines/sms

五、获取 Verify Service SID​

  1. 在 Twilio Console 左侧导航栏进入 Verify → Services。
  2. 点击 Create New 按钮，输入服务名称（如 sms_verify）并选择验证码场景。
  3. 保存后，获取 Verify Service SID（以 VA 开头）

六、在 HAP 中配置 Twilio​

  1. 进入【组织管理】>【集成】>【系统服务】
  2. 点击【Twilio 国际短信】卡片中的【连接】
  3. 将前面获取的 API Key SID、API Key Secret、Verify Service SID、Messaging Service SID 依次填入并保存。

七、发送费用与范围​

  • 计费模式： 短信费用直接从您的 Twilio 账户中扣除，HAP 平台不参与扣费。

  • 支持范围： 支持全球主流国家和地区的短信下发。

八、国际短信收不到如何排查​

当用户配置完成后无法接收短信，请按以下顺序逐项排查，以高效定位问题根源。

1. 检查号码和格式​

  • 确认手机号状态正常，非虚拟号、黑名单号或异常号段。

  • 必须符合 E.164 国际标准格式。**以 + 开头，含国家码，(eg. +852) ** ，去除中间空格。

2. 核查国家/运营商限制​

  • 在 Messaging → Settings → Geo Permissions 确认目标国家未被禁用。

  • 确认接收国是否有特殊的报备要求（如 A2P、10DLC），未备案的发送可能被直接屏蔽。

3. 检查 Messaging Service 配置​

  • 确保服务下已绑定状态为 Active 的有效号码。

  • 检查是否开启了过高灵敏度的过滤规则（如 Spam 垃圾过滤），可尝试调低灵敏度。

4. 检查 Twilio Logs​

进入 Monitor → Logs → SMS Logs，通过手机号或 SID 筛选查看状态：

  • accepted/sent：已受理或已发出。

  • delivered：运营商已送达（若未收到请检查手机端拦截设置）。

  • failed：发送失败，请查看具体错误码定位问题（如 30003 频率限制、30004 号码无效、30005 地区限制）。

5. 检查账号状态与余额​

  • 确认账号为 Active 状态。

  • 确认余额充足。试用账号存在额度限制且可能无法发往特定国家。

6. 检查 Verify 配置是否正确（验证码场景）​

  • 在 Verify → Services 确认 Senders List 包含当前发送号，且该号已启用短信功能。

  • 使用控制台的 Send test SMS 功能确认 Twilio 端是否能正常发出。

7. 检查本地参数核查​

  • 确认填入 HAP 平台的 Messaging Service SID 或 API Key/Secret 准确无误（无多余空格）。

  • 确认目标号码未被代码逻辑硬编码为测试假号。

8. 联系官方支持​

若以上步骤均排查无误仍未解决问题，请提交工单联系 Twilio 官方技术支持。