Back to Details

telnyx-numbers-services-javascript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Numbers Services - JavaScript

Telnyx Numbers Services - JavaScript

Installation

安装

bash
npm install telnyx
bash
npm install telnyx

Setup

设置

javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
All examples below assume 
client
is already initialized as shown above.
javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
以下所有示例均假设
client
已按上述方式初始化。

Error Handling

错误处理

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:
javascript
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');
    }
  }
}
Common error codes: 
401
invalid API key, 
403
insufficient permissions, 
404
resource not found, 
422
validation error (check field formats), 
429
rate limited (retry with exponential backoff).
所有API调用都可能因网络错误、速率限制（429）、验证错误（422）或身份验证错误（401）而失败。在生产代码中务必处理错误：
javascript
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
速率受限（使用指数退避重试）。

Important Notes

重要说明

  • Pagination: List methods return an auto-paginating iterator. Use 
    for await (const item of result) { ... }
    to iterate through all pages automatically.
  • 分页： 列表方法返回一个自动分页的迭代器。使用
    for await (const item of result) { ... }
    自动遍历所有页面。

List your voice channels for non-US zones

列出非美国区域的语音通道

Returns the non-US voice channels for your account. voice channels allow you to use Channel Billing for calls to your Telnyx phone numbers. Please check the Telnyx Support Articles section for full information and examples of how to utilize Channel Billing.
GET /channel_zones
javascript
// Automatically fetches more pages as needed.
for await (const channelZoneListResponse of client.channelZones.list()) {
  console.log(channelZoneListResponse.id);
}
Returns: 
channels
(int64), 
countries
(array[string]), 
created_at
(string), 
id
(string), 
name
(string), 
record_type
(enum: channel_zone), 
updated_at
(string)
返回您账户的非美国区域语音通道。语音通道允许您对Telnyx电话号码的通话使用通道计费。请查看Telnyx支持文章部分获取关于如何使用通道计费的完整信息和示例。
GET /channel_zones
javascript
// Automatically fetches more pages as needed.
for await (const channelZoneListResponse of client.channelZones.list()) {
  console.log(channelZoneListResponse.id);
}
Returns: 
channels
(int64), 
countries
(array[string]), 
created_at
(string), 
id
(string), 
name
(string), 
record_type
(enum: channel_zone), 
updated_at
(string)

Update voice channels for non-US Zones

更新非美国区域的语音通道

Update the number of Voice Channels for the Non-US Zones. This allows your account to handle multiple simultaneous inbound calls to Non-US numbers. Use this endpoint to increase or decrease your capacity based on expected call volume.
PUT /channel_zones/{channel_zone_id}
— Required: 
channels
javascript
const channelZone = await client.channelZones.update('channel_zone_id', { channels: 0 });

console.log(channelZone.id);
Returns: 
channels
(int64), 
countries
(array[string]), 
created_at
(string), 
id
(string), 
name
(string), 
record_type
(enum: channel_zone), 
updated_at
(string)
更新非美国区域的语音通道数量。这允许您的账户处理多个同时打入的非美国号码来电。可根据预期通话量使用此端点增加或减少容量。
PUT /channel_zones/{channel_zone_id}
— Required: 
channels
javascript
const channelZone = await client.channelZones.update('channel_zone_id', { channels: 0 });

console.log(channelZone.id);
Returns: 
channels
(int64), 
countries
(array[string]), 
created_at
(string), 
id
(string), 
name
(string), 
record_type
(enum: channel_zone), 
updated_at
(string)

List dynamic emergency addresses

列出动态紧急地址

Returns the dynamic emergency addresses according to filters
GET /dynamic_emergency_addresses
javascript
// Automatically fetches more pages as needed.
for await (const dynamicEmergencyAddress of client.dynamicEmergencyAddresses.list()) {
  console.log(dynamicEmergencyAddress.id);
}
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)
根据筛选条件返回动态紧急地址
GET /dynamic_emergency_addresses
javascript
// Automatically fetches more pages as needed.
for await (const dynamicEmergencyAddress of client.dynamicEmergencyAddresses.list()) {
  console.log(dynamicEmergencyAddress.id);
}
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)

Create a dynamic emergency address.

创建动态紧急地址

Creates a dynamic emergency address.
POST /dynamic_emergency_addresses
— Required: 
house_number
, 
street_name
, 
locality
, 
administrative_area
, 
postal_code
, 
country_code
Optional: 
created_at
(string), 
extended_address
(string), 
house_suffix
(string), 
id
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)
javascript
const dynamicEmergencyAddress = await client.dynamicEmergencyAddresses.create({
  administrative_area: 'TX',
  country_code: 'US',
  house_number: '600',
  locality: 'Austin',
  postal_code: '78701',
  street_name: 'Congress',
});

console.log(dynamicEmergencyAddress.data);
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)
创建一个动态紧急地址。
POST /dynamic_emergency_addresses
— Required: 
house_number
, 
street_name
, 
locality
, 
administrative_area
, 
postal_code
, 
country_code
Optional: 
created_at
(string), 
extended_address
(string), 
house_suffix
(string), 
id
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)
javascript
const dynamicEmergencyAddress = await client.dynamicEmergencyAddresses.create({
  administrative_area: 'TX',
  country_code: 'US',
  house_number: '600',
  locality: 'Austin',
  postal_code: '78701',
  street_name: 'Congress',
});

console.log(dynamicEmergencyAddress.data);
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)

Get a dynamic emergency address

获取动态紧急地址

Returns the dynamic emergency address based on the ID provided
GET /dynamic_emergency_addresses/{id}
javascript
const dynamicEmergencyAddress = await client.dynamicEmergencyAddresses.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(dynamicEmergencyAddress.data);
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)
根据提供的ID返回动态紧急地址
GET /dynamic_emergency_addresses/{id}
javascript
const dynamicEmergencyAddress = await client.dynamicEmergencyAddresses.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(dynamicEmergencyAddress.data);
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)

Delete a dynamic emergency address

删除动态紧急地址

Deletes the dynamic emergency address based on the ID provided
DELETE /dynamic_emergency_addresses/{id}
javascript
const dynamicEmergencyAddress = await client.dynamicEmergencyAddresses.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(dynamicEmergencyAddress.data);
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)
根据提供的ID删除动态紧急地址
DELETE /dynamic_emergency_addresses/{id}
javascript
const dynamicEmergencyAddress = await client.dynamicEmergencyAddresses.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(dynamicEmergencyAddress.data);
Returns: 
administrative_area
(string), 
country_code
(enum: US, CA, PR), 
created_at
(string), 
extended_address
(string), 
house_number
(string), 
house_suffix
(string), 
id
(string), 
locality
(string), 
postal_code
(string), 
record_type
(string), 
sip_geolocation_id
(string), 
status
(enum: pending, activated, rejected), 
street_name
(string), 
street_post_directional
(string), 
street_pre_directional
(string), 
street_suffix
(string), 
updated_at
(string)

List dynamic emergency endpoints

列出美国区域的语音通道

Returns the dynamic emergency endpoints according to filters
GET /dynamic_emergency_endpoints
javascript
// Automatically fetches more pages as needed.
for await (const dynamicEmergencyEndpoint of client.dynamicEmergencyEndpoints.list()) {
  console.log(dynamicEmergencyEndpoint.dynamic_emergency_address_id);
}
Returns: 
callback_number
(string), 
caller_name
(string), 
created_at
(string), 
dynamic_emergency_address_id
(string), 
id
(string), 
record_type
(string), 
sip_from_id
(string), 
status
(enum: pending, activated, rejected), 
updated_at
(string)
返回您账户的美国区域语音通道。语音通道允许您对Telnyx电话号码的通话使用通道计费。请查看Telnyx支持文章部分获取关于如何使用通道计费的完整信息和示例。
GET /inbound_channels
javascript
const inboundChannels = await client.inboundChannels.list();

console.log(inboundChannels.data);
Returns: 
channels
(integer), 
record_type
(string)

Create a dynamic emergency endpoint.

更新美国区域的语音通道

Creates a dynamic emergency endpoints.
POST /dynamic_emergency_endpoints
— Required: 
dynamic_emergency_address_id
, 
callback_number
, 
caller_name
Optional: 
created_at
(string), 
id
(string), 
record_type
(string), 
sip_from_id
(string), 
status
(enum: pending, activated, rejected), 
updated_at
(string)
javascript
const dynamicEmergencyEndpoint = await client.dynamicEmergencyEndpoints.create({
  callback_number: '+13125550000',
  caller_name: 'Jane Doe Desk Phone',
  dynamic_emergency_address_id: '0ccc7b54-4df3-4bca-a65a-3da1ecc777f0',
});

console.log(dynamicEmergencyEndpoint.data);
Returns: 
callback_number
(string), 
caller_name
(string), 
created_at
(string), 
dynamic_emergency_address_id
(string), 
id
(string), 
record_type
(string), 
sip_from_id
(string), 
status
(enum: pending, activated, rejected), 
updated_at
(string)
更新美国区域的语音通道数量。这允许您的账户处理多个同时打入的美国号码来电。可根据预期通话量使用此端点增加或减少容量。
PATCH /inbound_channels
— Required: 
channels
javascript
const inboundChannel = await client.inboundChannels.update({ channels: 7 });

console.log(inboundChannel.data);
Returns: 
channels
(integer), 
record_type
(string)

Get a dynamic emergency endpoint

列出所有使用通道计费的号码

Returns the dynamic emergency endpoint based on the ID provided
GET /dynamic_emergency_endpoints/{id}
javascript
const dynamicEmergencyEndpoint = await client.dynamicEmergencyEndpoints.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(dynamicEmergencyEndpoint.data);
Returns: 
callback_number
(string), 
caller_name
(string), 
created_at
(string), 
dynamic_emergency_address_id
(string), 
id
(string), 
record_type
(string), 
sip_from_id
(string), 
status
(enum: pending, activated, rejected), 
updated_at
(string)
检索所有使用通道计费的电话号码列表，按区域分组。
GET /list
javascript
const response = await client.list.retrieveAll();

console.log(response.data);
Returns: 
number_of_channels
(integer), 
numbers
(array[object]), 
zone_id
(string), 
zone_name
(string)

Delete a dynamic emergency endpoint

列出特定区域使用通道计费的号码

Deletes the dynamic emergency endpoint based on the ID provided
DELETE /dynamic_emergency_endpoints/{id}
javascript
const dynamicEmergencyEndpoint = await client.dynamicEmergencyEndpoints.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(dynamicEmergencyEndpoint.data);
Returns: 
callback_number
(string), 
caller_name
(string), 
created_at
(string), 
dynamic_emergency_address_id
(string), 
id
(string), 
record_type
(string), 
sip_from_id
(string), 
status
(enum: pending, activated, rejected), 
updated_at
(string)
检索特定区域使用通道计费的电话号码列表。
GET /list/{channel_zone_id}
javascript
const response = await client.list.retrieveByZone('channel_zone_id');

console.log(response.data);
Returns: 
number_of_channels
(integer), 
numbers
(array[object]), 
zone_id
(string), 
zone_name
(string)

List your voice channels for US Zone

获取语音信箱

Returns the US Zone voice channels for your account. voice channels allows you to use Channel Billing for calls to your Telnyx phone numbers. Please check the Telnyx Support Articles section for full information and examples of how to utilize Channel Billing.
GET /inbound_channels
javascript
const inboundChannels = await client.inboundChannels.list();

console.log(inboundChannels.data);
Returns: 
channels
(integer), 
record_type
(string)
返回电话号码的语音信箱设置
GET /phone_numbers/{phone_number_id}/voicemail
javascript
const voicemail = await client.phoneNumbers.voicemail.retrieve('123455678900');

console.log(voicemail.data);
Returns: 
enabled
(boolean), 
pin
(string)

Update voice channels for US Zone

创建语音信箱

Update the number of Voice Channels for the US Zone. This allows your account to handle multiple simultaneous inbound calls to US numbers. Use this endpoint to increase or decrease your capacity based on expected call volume.
PATCH /inbound_channels
— Required: 
channels
javascript
const inboundChannel = await client.inboundChannels.update({ channels: 7 });

console.log(inboundChannel.data);
Returns: 
channels
(integer), 
record_type
(string)
为电话号码创建语音信箱设置
POST /phone_numbers/{phone_number_id}/voicemail
Optional: 
enabled
(boolean), 
pin
(string)
javascript
const voicemail = await client.phoneNumbers.voicemail.create('123455678900');

console.log(voicemail.data);
Returns: 
enabled
(boolean), 
pin
(string)

List All Numbers using Channel Billing

更新语音信箱

Retrieve a list of all phone numbers using Channel Billing, grouped by Zone.
GET /list
javascript
const response = await client.list.retrieveAll();

console.log(response.data);
Returns: 
number_of_channels
(integer), 
numbers
(array[object]), 
zone_id
(string), 
zone_name
(string)
更新电话号码的语音信箱设置
PATCH /phone_numbers/{phone_number_id}/voicemail
Optional: 
enabled
(boolean), 
pin
(string)
javascript
const voicemail = await client.phoneNumbers.voicemail.update('123455678900');

console.log(voicemail.data);
Returns: 
enabled
(boolean), 
pin
(string)

List Numbers using Channel Billing for a specific Zone

—
Retrieve a list of phone numbers using Channel Billing for a specific Zone.
GET /list/{channel_zone_id}
javascript
const response = await client.list.retrieveByZone('channel_zone_id');

console.log(response.data);
Returns: 
number_of_channels
(integer), 
numbers
(array[object]), 
zone_id
(string), 
zone_name
(string)
—

Get voicemail

—
Returns the voicemail settings for a phone number
GET /phone_numbers/{phone_number_id}/voicemail
javascript
const voicemail = await client.phoneNumbers.voicemail.retrieve('123455678900');

console.log(voicemail.data);
Returns: 
enabled
(boolean), 
pin
(string)
—

Create voicemail

—
Create voicemail settings for a phone number
POST /phone_numbers/{phone_number_id}/voicemail
Optional: 
enabled
(boolean), 
pin
(string)
javascript
const voicemail = await client.phoneNumbers.voicemail.create('123455678900');

console.log(voicemail.data);
Returns: 
enabled
(boolean), 
pin
(string)
—

Update voicemail

—
Update voicemail settings for a phone number
PATCH /phone_numbers/{phone_number_id}/voicemail
Optional: 
enabled
(boolean), 
pin
(string)
javascript
const voicemail = await client.phoneNumbers.voicemail.update('123455678900');

console.log(voicemail.data);
Returns: 
enabled
(boolean), 
pin
(string)
—