telnyx-account-management-javascript

用途

该技能面向 Telnyx 平台的账户管理场景，提供 JavaScript SDK 示例，用于经销商（reseller）和企业场景下管理子账户（托管账户，managed account）及组织用户。

安装与初始化

安装命令：

npm install telnyx

初始化方式：

import Telnyx from 'telnyx';

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

文档中的全部示例均假定 client 已按上述方式初始化。

错误处理

所有 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 Key 无效，403 表示权限不足，404 表示资源未找到，422 表示校验错误（需检查字段格式），429 表示触发速率限制（应使用指数退避重试）。

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

主要能力

托管账户管理

列出当前用户管理的账户（用户需经 Telnyx 明确批准才能成为管理账户）：

// Automatically fetches more pages as needed.
for await (const managedAccountListResponse of client.managedAccounts.list()) {
  console.log(managedAccountListResponse.id);
}

接口：GET /managed_accounts。返回字段包括 api_user（string）、created_at（string）、email（email）、id（uuid）、managed_account_allow_custom_pricing（boolean）、manager_account_id（string）、organization_name（string）、record_type（enum: managed_account）、rollup_billing（boolean）、updated_at（string）。

创建新的托管账户（需经 Telnyx 明确批准成为管理账户）：

const managedAccount = await client.managedAccounts.create({
  business_name: "Larry's Cat Food Inc",
});

console.log(managedAccount.data);

接口：POST /managed_accounts，必填 business_name；可选 email（string）、managed_account_allow_custom_pricing（boolean）、password（string）、rollup_billing（boolean）。返回字段在列表字段基础上增加 api_key（string）、api_token（string）、balance（object）。

查看可分配的全球出站信道信息（仅账户管理者可用）：

const response = await client.managedAccounts.getAllocatableGlobalOutboundChannels();

console.log(response.data);

接口：GET /managed_accounts/allocatable_global_outbound_channels。返回 allocatable_global_outbound_channels（integer）、managed_account_allow_custom_pricing（boolean）、record_type（string）、total_global_channels_allocated（integer）。

检索单个托管账户：

const managedAccount = await client.managedAccounts.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(managedAccount.data);

接口：GET /managed_accounts/{id}。

更新托管账户：

const managedAccount = await client.managedAccounts.update('550e8400-e29b-41d4-a716-446655440000');

console.log(managedAccount.data);

接口：PATCH /managed_accounts/{id}，可选 managed_account_allow_custom_pricing（boolean）。

禁用托管账户（禁止其使用 Telnyx 服务，包括收发电话与短信；进行中的通话不受影响；该账户及其子用户将无法再通过 mission control portal 登录）：

const response = await client.managedAccounts.actions.disable('550e8400-e29b-41d4-a716-446655440000');

console.log(response.data);

接口：POST /managed_accounts/{id}/actions/disable。

启用托管账户（使其及其子用户可使用 Telnyx 服务）：

const response = await client.managedAccounts.actions.enable('550e8400-e29b-41d4-a716-446655440000');

console.log(response.data);

接口：POST /managed_accounts/{id}/actions/enable，可选 reenable_all_connections（boolean）。

更新分配给某托管账户的可分配全球出站信道数量：

const response = await client.managedAccounts.updateGlobalChannelLimit('550e8400-e29b-41d4-a716-446655440000');

console.log(response.data);

接口：PATCH /managed_accounts/{id}/update_global_channel_limit，可选 channel_limit（integer）。返回 channel_limit（integer）、email（string）、id（string）、manager_account_id（string）、record_type（string）。

组织用户管理

列出组织中的用户：

// Automatically fetches more pages as needed.
for await (const organizationUser of client.organizations.users.list()) {
  console.log(organizationUser.id);
}

接口：GET /organizations/users。返回字段包括 created_at（string）、email（email）、groups（array[object]）、id（string）、last_sign_in_at（string | null）、organization_user_bypasses_sso（boolean）、record_type（string）、user_status（enum: enabled, disabled, blocked）。

获取组织用户分组报告（返回全部用户及其分组关系，不带分页，始终包含分组信息；可通过指定 content-type 头以 JSON 或 CSV 格式获取）：

const response = await client.organizations.users.getGroupsReport();

console.log(response.data);

接口：GET /organizations/users/users_groups_report。

获取单个组织用户：

const user = await client.organizations.users.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(user.data);

接口：GET /organizations/users/{id}。

删除组织用户：

const action = await client.organizations.users.actions.remove('550e8400-e29b-41d4-a716-446655440000');

console.log(action.data);

接口：POST /organizations/users/{id}/actions/remove。

适用场景

经销商或企业需要在 JavaScript 项目中批量管理子账户。
需要通过代码创建、启停托管账户并调整其全球出站信道限额。
需要以编程方式查看组织内用户及分组信息、删除组织用户。

限制

托管账户的创建者需经 Telnyx 明确批准，才能成为管理账户。
查看可分配全球出站信道信息仅账户管理者可用。
禁用托管账户时，进行中的通话不受影响。
需配置有效的 Telnyx API Key。
其他未在资料中说明的限制暂未提供。