telnyx-numbers-services-curl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx Numbers Services - curl

Telnyx 号码服务 - curl

Installation

安装

text

undefined

text

undefined

curl is pre-installed on macOS, Linux, and Windows 10+

curl在macOS、Linux和Windows 10及以上版本中已预安装

undefined

undefined

Setup

配置

bash

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

All examples below use

$TELNYX_API_KEY

for authentication.

bash

export TELNYX_API_KEY="YOUR_API_KEY_HERE"

以下所有示例均使用

$TELNYX_API_KEY

进行身份验证。

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:

bash

undefined

所有API调用都可能出现网络错误、速率限制错误（429）、参数校验错误（422）或身份验证错误（401）。在生产代码中请务必做好错误处理：

bash

undefined

Check HTTP status code in response

检查响应中的HTTP状态码

response=$(curl -s -w "\n%{http_code}"
-X POST "https://api.telnyx.com/v2/messages"
-H "Authorization: Bearer $TELNYX_API_KEY"
-H "Content-Type: application/json"
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')

http_code=$(echo "$response" | tail -1) body=$(echo "$response" | sed '$d')

case $http_code in 2*) echo "Success: $body" ;; 422) echo "Validation error — check required fields and formats" ;; 429) echo "Rate limited — retry after delay"; sleep 1 ;; 401) echo "Authentication failed — check TELNYX_API_KEY" ;; *) echo "Error $http_code: $body" ;; esac


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).

http_code=$(echo "$response" | tail -1) body=$(echo "$response" | sed '$d')

case $http_code in 2*) echo "请求成功: $body" ;; 422) echo "参数校验错误 — 请检查必填字段和格式是否正确" ;; 429) echo "触发速率限制 — 请延迟后重试"; sleep 1 ;; 401) echo "身份验证失败 — 请检查TELNYX_API_KEY是否正确" ;; *) echo "请求错误 $http_code: $body" ;; esac


常见错误码：`401` API密钥无效，`403` 权限不足，`404` 资源未找到，`422` 参数校验错误（请检查字段格式），`429` 触发速率限制（请使用指数退避策略重试）。

Important Notes

重要说明

Pagination: List endpoints return paginated results. Use
```
page[number]
```
and
```
page[size]
```
query parameters to navigate pages. Check
```
meta.total_pages
```
in the response.

分页： 列表类接口返回分页结果。使用
```
page[number]
```
和
```
page[size]
```
查询参数来分页查询，可查看响应中的
```
meta.total_pages
```
获取总页数。

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/channel_zones"

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/channel_zones"

返回参数：

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

bash

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channels": 0
}' \
  "https://api.telnyx.com/v2/channel_zones/{channel_zone_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}

— 必填参数：

channels

bash

curl \
  -X PUT \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channels": 0
}' \
  "https://api.telnyx.com/v2/channel_zones/{channel_zone_id}"

返回参数：

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_addresses"

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_addresses"

返回参数：

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)

bash

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "house_number": "600",
  "street_name": "Congress",
  "locality": "Austin",
  "administrative_area": "TX",
  "postal_code": "78701",
  "country_code": "US"
}' \
  "https://api.telnyx.com/v2/dynamic_emergency_addresses"

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

— 必填参数：

house_number

street_name

locality

administrative_area

postal_code

country_code

可选参数：

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)

bash

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "house_number": "600",
  "street_name": "Congress",
  "locality": "Austin",
  "administrative_area": "TX",
  "postal_code": "78701",
  "country_code": "US"
}' \
  "https://api.telnyx.com/v2/dynamic_emergency_addresses"

返回参数：

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}

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_addresses/550e8400-e29b-41d4-a716-446655440000"

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}

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_addresses/550e8400-e29b-41d4-a716-446655440000"

返回参数：

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}

bash

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/dynamic_emergency_addresses/550e8400-e29b-41d4-a716-446655440000"

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}

bash

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/dynamic_emergency_addresses/550e8400-e29b-41d4-a716-446655440000"

返回参数：

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_endpoints"

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 /dynamic_emergency_endpoints

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_endpoints"

返回参数：

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)

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)

bash

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dynamic_emergency_address_id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
  "callback_number": "+13125550000",
  "caller_name": "Jane Doe Desk Phone"
}' \
  "https://api.telnyx.com/v2/dynamic_emergency_endpoints"

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)

创建一个动态紧急端点。

POST /dynamic_emergency_endpoints

— 必填参数：

dynamic_emergency_address_id

callback_number

caller_name

可选参数：

created_at

(string),

id

(string),

record_type

(string),

sip_from_id

(string),

status

(enum: pending, activated, rejected),

updated_at

(string)

bash

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dynamic_emergency_address_id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
  "callback_number": "+13125550000",
  "caller_name": "Jane Doe Desk Phone"
}' \
  "https://api.telnyx.com/v2/dynamic_emergency_endpoints"

返回参数：

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 a dynamic emergency endpoint

查询单个动态紧急端点

Returns the dynamic emergency endpoint based on the ID provided

GET /dynamic_emergency_endpoints/{id}

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_endpoints/550e8400-e29b-41d4-a716-446655440000"

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)

根据传入的ID返回对应的动态紧急端点

GET /dynamic_emergency_endpoints/{id}

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/dynamic_emergency_endpoints/550e8400-e29b-41d4-a716-446655440000"

返回参数：

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)

Delete a dynamic emergency endpoint

删除动态紧急端点

Deletes the dynamic emergency endpoint based on the ID provided

DELETE /dynamic_emergency_endpoints/{id}

bash

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/dynamic_emergency_endpoints/550e8400-e29b-41d4-a716-446655440000"

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)

根据传入的ID删除对应的动态紧急端点

DELETE /dynamic_emergency_endpoints/{id}

bash

curl \
  -X DELETE \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/dynamic_emergency_endpoints/550e8400-e29b-41d4-a716-446655440000"

返回参数：

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)

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/inbound_channels"

Returns:

channels

(integer),

record_type

(string)

返回你账户下美国区域的语音通道。语音通道支持你对Telnyx号码的通话使用通道计费模式。请查阅Telnyx支持文章板块，了解通道计费的完整说明和使用示例。

GET /inbound_channels

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/inbound_channels"

返回参数：

channels

(integer),

record_type

(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

bash

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channels": 7
}' \
  "https://api.telnyx.com/v2/inbound_channels"

Returns:

channels

(integer),

record_type

(string)

更新美国区域的语音通道数量。调整后你的账户可支持更多美国号码的同时呼入通话。你可以根据预期通话量使用该接口升降服务容量。

PATCH /inbound_channels

— 必填参数：

channels

bash

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channels": 7
}' \
  "https://api.telnyx.com/v2/inbound_channels"

返回参数：

channels

(integer),

record_type

(string)

List All Numbers using Channel Billing

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

Retrieve a list of all phone numbers using Channel Billing, grouped by Zone.

GET /list

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/list"

Returns:

number_of_channels

(integer),

numbers

(array[object]),

zone_id

(string),

zone_name

(string)

获取按区域分组的所有使用通道计费的电话号码列表。

GET /list

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/list"

返回参数：

number_of_channels

(integer),

numbers

(array[object]),

zone_id

(string),

zone_name

(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}

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/list/{channel_zone_id}"

Returns:

number_of_channels

(integer),

numbers

(array[object]),

zone_id

(string),

zone_name

(string)

获取指定区域下使用通道计费的电话号码列表。

GET /list/{channel_zone_id}

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/list/{channel_zone_id}"

返回参数：

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

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail"

Returns:

enabled

(boolean),

pin

(string)

返回指定电话号码的语音信箱配置

GET /phone_numbers/{phone_number_id}/voicemail

bash

curl -H "Authorization: Bearer $TELNYX_API_KEY" "https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail"

返回参数：

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)

bash

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail"

Returns:

enabled

(boolean),

pin

(string)

为指定电话号码创建语音信箱配置

POST /phone_numbers/{phone_number_id}/voicemail

可选参数：

enabled

(boolean),

pin

(string)

bash

curl \
  -X POST \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail"

返回参数：

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)

bash

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail"

Returns:

enabled

(boolean),

pin

(string)

更新指定电话号码的语音信箱配置

PATCH /phone_numbers/{phone_number_id}/voicemail

可选参数：

enabled

(boolean),

pin

(string)

bash

curl \
  -X PATCH \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail"

返回参数：

enabled

(boolean),

pin

(string)