telnyx-account-management-javascript

用途

本技能面向经销商（reseller）与企业（enterprise）场景，提供使用 Telnyx JavaScript SDK 管理子账户（托管账户，managed accounts）以及组织用户的示例代码。

安装与初始化

安装命令：

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

错误处理

所有 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 明确批准才能成为管理账户。

GET /managed_accounts

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

返回字段：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 明确批准才能成为管理账户。

POST /managed_accounts — 必填：business_name

可选：email (string)、managed_account_allow_custom_pricing (boolean)、password (string)、rollup_billing (boolean)

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

console.log(managedAccount.data);

返回字段：api_key (string)、api_token (string)、api_user (string)、balance (object)、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)。

查询可分配的全局外呼通道

显示当前用户可分配的全局外呼通道信息。仅账户管理者可用。

GET /managed_accounts/allocatable_global_outbound_channels

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

console.log(response.data);

返回字段：allocatable_global_outbound_channels (integer)、managed_account_allow_custom_pricing (boolean)、record_type (string)、total_global_channels_allocated (integer)。

获取单个托管账户

GET /managed_accounts/{id}

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

console.log(managedAccount.data);

返回字段同创建接口。

更新托管账户

PATCH /managed_accounts/{id}

可选：managed_account_allow_custom_pricing (boolean)

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

console.log(managedAccount.data);

返回字段同创建接口。

禁用托管账户

禁用托管账户，禁止其使用 Telnyx 服务，包括拨打或接听电话及收发短信。正在进行的通话不受影响。该托管账户及其子用户将无法再通过 mission control portal 登录。

POST /managed_accounts/{id}/actions/disable

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

console.log(response.data);

返回字段同创建接口。

启用托管账户

启用托管账户及其子用户使用 Telnyx 服务。

POST /managed_accounts/{id}/actions/enable

可选：reenable_all_connections (boolean)

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

console.log(response.data);

返回字段同创建接口。

更新托管账户的全局外呼通道限额

PATCH /managed_accounts/{id}/update_global_channel_limit

可选：channel_limit (integer)

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

console.log(response.data);

返回字段：channel_limit (integer)、email (string)、id (string)、manager_account_id (string)、record_type (string)。

组织用户管理

列出组织用户

返回组织中的用户列表。

GET /organizations/users

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

返回字段：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 格式获取报告。

GET /organizations/users/users_groups_report

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

console.log(response.data);

返回字段同上。

获取组织用户

GET /organizations/users/{id}

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

console.log(user.data);

返回字段同上。

删除组织用户

POST /organizations/users/{id}/actions/remove

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

console.log(action.data);

返回字段同上。

适用场景与限制

适用于经销商和企业通过 JavaScript 程序化管理 Telnyx 子账户与组织用户的场景。使用托管账户功能需经 Telnyx 明确批准成为管理账户；可分配全局外呼通道接口仅账户管理者可用。资料未提供收费、价格、平台支持范围等更多信息。