telnyx-10dlc-javascript

用途

Telnyx 10DLC - JavaScript 是 Telnyx 官方提供的 JavaScript SDK 技能，面向美国 A2P（应用到个人）短信合规场景，用于完成 10DLC 品牌（Brand）与活动（Campaign）的注册，并将电话号码分配给活动。

安装与初始化

安装命令：

npm install telnyx@6.74.2

初始化：

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

主要能力

核心任务

创建品牌：client.messaging10dlc.brand.create() — POST /10dlc/brand。必填参数包括 entityType、displayName、country、email、vertical。主要响应字段包括 brandId、identityStatus、status、displayName、state、altBusinessId。
提交活动：client.messaging10dlc.campaignBuilder.submit() — POST /10dlc/campaignBuilder。必填参数包括 brandId、description、usecase。主要响应字段包括 campaignId、brandId、campaignStatus、submissionStatus、failureReasons、status。
将消息配置文件分配给活动：client.messaging10dlc.phoneNumberAssignmentByProfile.assign() — POST /10dlc/phoneNumberAssignmentByProfile。必填参数包括 messagingProfileId、campaignId。主要响应字段包括 messagingProfileId、campaignId、taskId、tcrCampaignId。

重要辅助操作

获取品牌：client.messaging10dlc.brand.retrieve() — GET /10dlc/brand/{brandId}
按用例资格查询：client.messaging10dlc.campaignBuilder.brand.qualifyByUsecase() — GET /10dlc/campaignBuilder/brand/{brandId}/usecase/{usecase}
创建电话号码活动：client.messaging10dlc.phoneNumberCampaigns.create() — POST /10dlc/phone_number_campaigns
获取活动：client.messaging10dlc.campaign.retrieve() — GET /10dlc/campaign/{campaignId}
列出品牌：client.messaging10dlc.brand.list() — GET /10dlc/brand
按 ID 获取品牌反馈：client.messaging10dlc.brand.getFeedback() — GET /10dlc/brand/feedback/{brandId}

其他操作

技能还索引了品牌 SMS OTP 状态查询、更新品牌、删除品牌、重发品牌 2FA 邮件、列出/订购/导入外部审核、重新审核品牌、触发与验证品牌 SMS OTP、列出活动、接受共享活动、获取活动成本、更新活动、停用活动、提交活动申诉、获取活动 MNO 元数据、获取活动操作状态、获取 OSR 活动属性、获取共享状态等操作，均提供对应的 SDK 方法与端点。

使用方式

错误处理

所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败。生产代码中应始终处理错误：

try {
  const telnyxBrand = await client.messaging10dlc.brand.create({
    country: 'US',
    displayName: 'ABC Mobile',
    email: 'support@example.com',
    entityType: 'PRIVATE_PROFIT',
    vertical: 'TECHNOLOGY',
  });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}

常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 校验错误（检查字段格式），429 限流（使用指数退避重试）。

分页

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

Webhook 验证

Telnyx 使用 Ed25519 对 Webhook 签名。每个请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。生产环境应始终验证签名：

// In your webhook handler (e.g., Express — use raw body, not parsed 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,
    });
    // Signature valid — event is the parsed webhook payload
    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 字段

活动状态更新 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 合规注册的 JavaScript 项目。典型流程为：创建品牌 → 提交活动 → 分配消息配置文件 → 关联电话号码。

限制与注意事项

10DLC 是顺序流程：先创建品牌，再提交活动，然后附加消息基础设施（如消息配置文件）。
仅完成注册调用不足以发送消息；在分配步骤成功完成之前，消息无法使用该活动。
应将注册状态字段视为控制流的一部分，在返回的状态字段确认之前，不要假设活动已可发送。
不要臆造 Telnyx 参数、枚举、响应字段或 Webhook 字段。若所需参数、枚举或响应字段未在技能内联展示，应先阅读 references/api-details.md。
使用“其他操作”中的任何操作前，应先阅读可选参数部分和响应模式部分。
阅读或匹配内联示例之外的 Webhook 字段前，应先阅读 Webhook 负载参考。
关于收费、价格、平台支持范围等具体信息，资料中暂未提供。