telnyx-messaging-profiles-javascript

用途

本技能面向使用 JavaScript 的开发者，帮助通过 Telnyx API 创建和管理消息配置文件（Messaging Profiles）。消息配置文件用于组织消息发送相关的设置，包括号码池、粘性发送（sticky sender）和地理匹配（geomatch）等功能，并可配置短代码（short codes）以支持高容量消息发送。

安装与初始化

安装依赖：

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 已按上述方式初始化。

主要能力

消息配置文件管理

列出消息配置文件：GET /messaging_profiles，返回结果支持自动分页迭代器，可用 for await (const item of result) { ... } 自动遍历所有页面。
创建消息配置文件：POST /messaging_profiles，必填字段为 name 和 whitelisted_destinations；可选字段包括 ai_assistant_id、alpha_sender、daily_spend_limit、daily_spend_limit_enabled、enabled、health_webhook_url、mms_fall_back_to_sms、mms_transcoding、mobile_only、number_pool_settings、resource_group_id、smart_encoding、url_shortener_settings、webhook_api_version、webhook_failover_url、webhook_url。
检索消息配置文件：GET /messaging_profiles/{id}。
更新消息配置文件：PATCH /messaging_profiles/{id}。
删除消息配置文件：DELETE /messaging_profiles/{id}。

配置文件对象返回字段包括：ai_assistant_id、alpha_sender、created_at、daily_spend_limit、daily_spend_limit_enabled、enabled、health_webhook_url、id、mms_fall_back_to_sms、mms_transcoding、mobile_only、name、number_pool_settings、organization_id、record_type、redaction_enabled、redaction_level、resource_group_id、smart_encoding、updated_at、url_shortener_settings、v1_secret、webhook_api_version、webhook_failover_url、webhook_url、whitelisted_destinations。

关联电话号码查询

列出与某消息配置文件关联的电话号码：GET /messaging_profiles/{id}/phone_numbers，支持自动分页。返回字段包括 country_code、created_at、eligible_messaging_products、features、health、id、messaging_product、messaging_profile_id、organization_id、phone_number、record_type、tags、traffic_type、type、updated_at。

短代码管理

列出某消息配置文件关联的短代码：GET /messaging_profiles/{id}/short_codes，支持自动分页。
列出短代码：GET /short_codes，支持自动分页。
检索短代码：GET /short_codes/{id}。
更新短代码：PATCH /short_codes/{id}，必填字段为 messaging_profile_id，可选字段为 tags。将 messaging_profile_id 设为 null 或空字符串可解除短代码与配置文件的绑定；通过 tags 字段（字符串数组）可添加或更新标签。

短代码对象返回字段包括：country_code、created_at、id、messaging_profile_id、record_type、short_code、tags、updated_at。

使用方式

所有 API 调用均通过初始化后的 client 对象进行，例如：

const messagingProfile = await client.messagingProfiles.create({
  name: 'My name',
  whitelisted_destinations: ['US'],
});

console.log(messagingProfile.data);

列表方法返回自动分页迭代器，可自动获取更多页面：

for await (const messagingProfile of client.messagingProfiles.list()) {
  console.log(messagingProfile.id);
}

错误处理

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

try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    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 触发限流（使用指数退避重试）。

适用场景

适用于需要通过 JavaScript 程序化管理 Telnyx 消息发送配置的开发者，例如批量创建和维护消息配置文件、管理号码池与粘性发送设置、配置地理匹配、为高容量消息发送绑定短代码，以及查询配置文件关联的电话号码和短代码。

限制

本技能资料仅提供 JavaScript SDK 的 API 调用说明与示例，未提供其他语言版本、定价、平台支持范围或性能指标等信息。