telnyx-10dlc-javascript

用途

本技能用于美国 A2P（应用到个人）短信的 10DLC 合规注册流程，基于 Telnyx 的 JavaScript/Node.js SDK 实现。10DLC 是美国运营商对本地号码用于商业短信的注册要求，本技能覆盖品牌注册、活动提交以及将电话号码或消息配置文件分配到活动的完整链路。

主要能力

核心任务包括：

创建品牌（Brand）：调用 client.messaging10dlc.brand.create()（POST /10dlc/brand），必填参数为 entityType、displayName、country、email、vertical，可选参数包括 companyName、firstName、lastName 等。返回字段包含 brandId、identityStatus、status、displayName、state、altBusinessId。
提交活动（Campaign）：调用 client.messaging10dlc.campaignBuilder.submit()（POST /10dlc/campaignBuilder），必填参数为 brandId、description、usecase，可选参数包括 ageGated、autoRenewal、directLending 等。返回字段包含 campaignId、brandId、campaignStatus、submissionStatus、failureReasons、status。
分配消息配置文件到活动：调用 client.messaging10dlc.phoneNumberAssignmentByProfile.assign()（POST /10dlc/phoneNumberAssignmentByProfile），必填参数为 messagingProfileId、campaignId，可选参数为 tcrCampaignId。返回字段包含 messagingProfileId、campaignId、taskId、tcrCampaignId。

辅助操作包括：获取品牌（GET /10dlc/brand/{brandId}）、按用例查询品牌资格（GET /10dlc/campaignBuilder/brand/{brandId}/usecase/{usecase}）、创建电话号码活动（POST /10dlc/phone_number_campaigns）、获取活动（GET /10dlc/campaign/{campaignId}）、列出品牌（GET /10dlc/brand，支持自动分页迭代）、获取品牌反馈（GET /10dlc/brand/feedback/{brandId}）等。

使用方式

安装依赖：

npm install telnyx@6.74.2

初始化客户端：

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'],
});

错误处理需覆盖网络错误（APIConnectionError）、速率限制（RateLimitError，429）、验证错误（422）和认证错误（401）。常见错误码：401 无效 API 密钥、403 权限不足、404 资源未找到、422 验证错误、429 速率限制（建议指数退避重试）。

分页：列表方法返回自动分页迭代器，使用 for await (const item of result) { ... } 自动遍历所有页面。

Webhook 验证：Telnyx 使用 Ed25519 签名，请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。生产环境必须验证签名，使用原始请求体（非解析后的 JSON）：

app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await client.webhooks.unwrap(req.body.toString(), {
      headers: req.headers,
    });
    console.log('Received event:', event.data.event_type);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.status(400).send('Invalid signature');
  }
});

活动状态更新 Webhook 字段包括 brandId、campaignId、createDate、cspId、isTMobileRegistered、type（枚举：TELNYX_EVENT、REGISTRATION、MNO_REVIEW、TELNYX_REVIEW、NUMBER_POOL_PROVISIONED、NUMBER_POOL_DEPROVISIONED、TCR_EVENT、VERIFIED）、description、status（枚举：ACCEPTED、REJECTED、DORMANT、success、failed）。

适用场景

适用于需要在美国通过 Telnyx 发送 A2P 短信的开发者，尤其是需要完成 10DLC 品牌与活动注册、将电话号码或消息配置文件绑定到活动、并处理注册状态与 Webhook 回调的集成场景。

限制与注意事项

10DLC 流程具有顺序性：先创建品牌，再提交活动，最后附加消息基础设施（如消息配置文件）。
注册调用本身不足以发送消息，必须成功完成分配步骤后消息才能使用该活动。
应将注册状态字段视为控制流的一部分，在返回的状态字段确认之前，不要假设活动已可发送。
不要臆造 Telnyx 参数、枚举、响应字段或 Webhook 字段；未内联的字段需查阅 references/api-details.md 或 Webhook 负载参考。
使用 Additional Operations 中的操作前，需先阅读可选参数与响应模式部分。
本技能未提供收费、价格或平台支持范围等具体信息。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项