用途:面向美国 A2P 短信合规的 Telnyx 10DLC 注册流程,使用 curl 直接调用 Telnyx API v2。
设置:curl 在 macOS、Linux 和 Windows 10+ 上已预装;先执行 export TELNYX_API_KEY="YOUR_API_KEY_HERE",后续请求以 Authorization: Bearer $TELNYX_API_KEY 认证。
主要能力:
- 创建品牌:POST /10dlc/brand,必填 entityType、displayName、country(ISO2 两位)、email、vertical;返回 data.brandId、identityStatus、status 等。
- 提交活动:POST /10dlc/campaignBuilder,必填 brandId、description、usecase;返回 campaignId、campaignStatus、submissionStatus、failureReasons 等。
- 分配消息配置文件:POST /10dlc/phoneNumberAssignmentByProfile,必填 messagingProfileId、campaignId;返回 taskId 等。
- 支持操作:查询品牌、按 usecase 资质查询、创建电话号码活动、查询活动、列出品牌、查询品牌反馈等。更多低频操作见 references/api-details.md。
关键流程与限制:10DLC 是顺序流程——先建品牌,再提交活动,然后关联消息配置文件等基础设施;仅完成注册调用不够,活动在分配步骤成功前不能用于发消息;应将注册状态字段纳入控制流,状态确认前不得假定活动可发送。
错误处理:API 可能因网络错误、限流(429)、校验错误(422)、认证错误(401)失败,生产代码需处理;403 权限不足、404 资源不存在、429 限流建议指数退避重试。列表端点分页,使用 page[number] 与 page[size],查看 meta.total_pages。
Webhook:Telnyx 使用 Ed25519 签名,请求头含 telnyx-signature-ed25519 和 telnyx-timestamp;生产环境应验签,时间戳超过 5 分钟应拒绝以防重放;端点须在 2 秒内返回 2xx,否则最多重试 3 次;公钥来自 Telnyx Portal > Account Settings > Keys & Credentials。活动状态 webhook 字段包括 brandId、campaignId、createDate、cspId、isTMobileRegistered、type、description、status。
注意:不要自行编造 Telnyx 参数、枚举、响应字段或 webhook 字段;未内联展示的字段应先读对应参考文件。