telnyx-messaging-profiles-javascript

Telnyx Messaging Profiles - JavaScript 是一个面向 JavaScript 开发者的技能文档，说明如何使用 Telnyx 官方的 npm 包 telnyx 来创建和管理消息配置文件（Messaging Profiles），并配置短码（short codes）用于高流量消息发送。该技能以 SDK 调用示例为核心，覆盖从初始化到各类增删改查操作。

一、用途 用于通过 JavaScript 代码管理 Telnyx 的消息配置文件，包括号码池（number pools）、粘性发送方（sticky sender）、地理匹配（geomatch）等功能的配置，以及为高流量消息发送配置短码。

二、安装与初始化 安装命令：npm install telnyx 初始化示例： import Telnyx from 'telnyx'; const client = new Telnyx({ apiKey: process.env['TELNYX_API_KEY'] }); 其中 apiKey 为默认配置项，可省略，但示例默认通过环境变量 TELNYX_API_KEY 传入。后续所有示例均假定 client 已按上述方式初始化。

三、错误处理 文档强调生产代码应始终处理错误。API 调用可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败。示例展示了针对 Telnyx.APIConnectionError（网络错误，建议检查连通性并重试）、Telnyx.RateLimitError（429 限流，建议等待并按指数退避重试，可通过 err.headers?.['retry-after'] 获取重试等待时间）、Telnyx.APIError（打印状态码与消息，422 时提示校验错误）的处理方式。常见错误码包括：401 无效 API 密钥、403 权限不足、404 资源不存在、422 校验错误（检查字段格式）、429 限流（使用指数退避重试）。

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

五、主要能力与 API 操作

1. 列出消息配置文件：GET /messaging_profiles，返回字段包括 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 等。
2. 创建消息配置文件：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。
3. 检索消息配置文件：GET /messaging_profiles/{id}。
4. 更新消息配置文件：PATCH /messaging_profiles/{id}，可选字段包括 alpha_sender、created_at、daily_spend_limit、daily_spend_limit_enabled、enabled、id、mms_fall_back_to_sms、mms_transcoding、mobile_only、name、number_pool_settings、record_type、smart_encoding、updated_at、url_shortener_settings、v1_secret、webhook_api_version、webhook_failover_url、webhook_url、whitelisted_destinations。
5. 删除消息配置文件：DELETE /messaging_profiles/{id}。
6. 列出消息配置文件关联的电话号码：GET /messaging_profiles/{id}/phone_numbers，返回 phoneNumberWithMessagingSettings 对象，字段包括 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（long-code、toll-free、short-code、longcode、tollfree、shortcode）、updated_at。
7. 列出消息配置文件关联的短码：GET /messaging_profiles/{id}/short_codes。
8. 列出短码：GET /short_codes。
9. 检索短码：GET /short_codes/{id}。
10. 更新短码：PATCH /short_codes/{id}，必填 messaging_profile_id，可选 tags（字符串数组）。若要将短码从某个配置文件解绑，可将 messaging_profile_id 设为 null 或空字符串。返回字段包括 country_code、created_at、id、messaging_profile_id、record_type、short_code、tags、updated_at。

六、适用场景 适用于需要在 JavaScript 项目中通过 Telnyx API 管理消息配置文件、号码池、粘性发送方、地理匹配配置，以及配置短码以支持高流量消息发送的开发者。

七、限制与暂未提供的信息 文档未说明价格、收费模式、速率限制的具体阈值或配额、具体的号码池/粘性发送方/地理匹配配置字段的详细说明；这些功能细节的字段虽在返回结构中提及（如 number_pool_settings），但未展开。