用途
Telnyx Numbers - JavaScript 是 Telnyx 电话号码管理能力的 JavaScript SDK 技能，用于在应用中搜索、订购和管理电话号码。它面向需要以编程方式完成号码采购与配置的开发者，覆盖从号码查询到订单履约的完整流程。
安装与初始化
安装命令：
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 已按上述方式初始化。
主要能力
核心任务包括：
- 搜索可用电话号码：client.availablePhoneNumbers.list()，对应 GET /available_phone_numbers，支持 filter 过滤参数，返回 phoneNumber、recordType、quickship、reservable、bestEffort、costInformation 等字段。
- 创建号码订单：client.numberOrders.create()，对应 POST /number_orders，必填 phone_numbers，可选 connection_id、messaging_profile_id、billing_group_id 等，返回订单 id、status、phoneNumbersCount、requirementsMet 等。
- 查询号码订单状态：client.numberOrders.retrieve()，对应 GET /number_orders/{number_order_id}，用于判断履约是否完成或是否仍有未满足的要求。
重要辅助操作包括：创建与查询号码预留（numberReservations）、高级订单（advancedOrders）的列表、创建、更新与查询、可用号码块（availablePhoneNumberBlocks）、评论（comments）的列表与创建、国家覆盖（countryCoverage）、客户服务记录（customerServiceRecords）、非显式号码订单（inexplicitNumberOrders）、库存覆盖（inventoryCoverage）、移动网络运营商（mobileNetworkOperators）、网络覆盖（networkCoverage）、号码块订单（numberBlockOrders）、订单关联号码（numberOrderPhoneNumbers）、号码功能（numbersFeatures）、号码块任务（phoneNumberBlocks.jobs）、子号码订单（subNumberOrders）等。
使用方式
号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能有空格、短横线或括号。
列表方法返回自动分页迭代器，可使用 for await (const item of result) { ... } 自动遍历所有页。
错误处理：所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败，生产代码应始终处理错误。示例：
try {
const availablePhoneNumbers = await client.availablePhoneNumbers.list();
} 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 触发限流（使用指数退避重试）。
适用场景
适用于需要以编程方式采购和管理电话号码的业务流程，例如按地区、功能或覆盖范围筛选号码、批量下单、跟踪订单履约状态、管理号码预留与号码块，以及查询国家与网络覆盖情况。
限制与注意事项
不要自行编造 Telnyx 的参数、枚举、响应字段或 webhook 字段。如果所需参数、枚举或响应字段未在本技能中内联展示，应先阅读 references/api-details.md 再编写代码。在使用“Additional Operations”中的任何操作前，应先阅读可选参数部分和响应模式部分。