telnyx-numbers-services-java

用途

Telnyx Numbers Services - Java 是面向 Java 开发者的技能示例，用于通过 Telnyx Java SDK 配置电话号码相关的服务，包括语音信箱（voicemail）、语音通道（voice channels / Channel Billing）以及紧急服务（E911）中的动态紧急地址与动态紧急端点。该技能以代码示例形式展示如何调用 Telnyx API，帮助开发者在 Java 项目中集成这些号码管理能力。

安装与初始化

该技能使用 Telnyx Java SDK，版本为 6.89.0。

Maven 安装方式：

<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.89.0</version>
</dependency>

Gradle 安装方式：

implementation("com.telnyx.sdk:telnyx:6.89.0")

客户端初始化示例：

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

文档中所有示例均假设 client 已按上述方式初始化。

错误处理

所有 API 调用都可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败。生产代码中应始终处理错误：

import com.telnyx.sdk.errors.TelnyxServiceException;

try {
    var result = client.messages().send(params);
} catch (TelnyxServiceException e) {
    System.err.println("API error " + e.statusCode() + ": " + e.getMessage());
    if (e.statusCode() == 422) {
        System.err.println("Validation error — check required fields and formats");
    } else if (e.statusCode() == 429) {
        // Rate limited — wait and retry with exponential backoff
        Thread.sleep(1000);
    }
}

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

分页说明

列表方法返回一页数据。可使用 .autoPager() 自动迭代：for (var item : page.autoPager()) { ... }。如需手动控制，可使用 .hasNextPage() 与 .nextPage()。

主要能力

非美国区域语音通道

• 列出非美国区域的语音通道：GET /channel_zones，返回 channels（int64）、countries（array[string]）、created_at、id、name、record_type（channel_zone）、updated_at。
• 更新非美国区域的语音通道数量：PUT /channel_zones/{channel_zone_id}，必填参数 channels。用于根据预期通话量增加或减少容量，以处理对非美国号码的多个并发入站呼叫。

美国区域语音通道

• 列出美国区域的语音通道：GET /inbound_channels，返回 channels（integer）、record_type。
• 更新美国区域的语音通道数量：PATCH /inbound_channels，必填参数 channels。用于处理对美国号码的多个并发入站呼叫。

使用 Channel Billing 的号码列表

• 列出所有使用 Channel Billing 的号码（按 Zone 分组）：GET /list，返回 number_of_channels、numbers（array[object]）、zone_id、zone_name。
• 列出指定 Zone 使用 Channel Billing 的号码：GET /list/{channel_zone_id}，返回字段同上。

动态紧急地址（E911）

• 列出动态紧急地址：GET /dynamic_emergency_addresses，返回 administrative_area、country_code（US/CA/PR）、created_at、extended_address、house_number、house_suffix、id、locality、postal_code、record_type、sip_geolocation_id、status（pending/activated/rejected）、street_name、street_post_directional、street_pre_directional、street_suffix、updated_at。
• 创建动态紧急地址：POST /dynamic_emergency_addresses，必填 house_number、street_name、locality、administrative_area、postal_code、country_code。
• 获取动态紧急地址：GET /dynamic_emergency_addresses/{id}。
• 删除动态紧急地址：DELETE /dynamic_emergency_addresses/{id}。

动态紧急端点（E911）

• 列出动态紧急端点：GET /dynamic_emergency_endpoints，返回 callback_number、caller_name、created_at、dynamic_emergency_address_id、id、record_type、sip_from_id、status（pending/activated/rejected）、updated_at。
• 创建动态紧急端点：POST /dynamic_emergency_endpoints，必填 dynamic_emergency_address_id、callback_number、caller_name。
• 获取动态紧急端点：GET /dynamic_emergency_endpoints/{id}。
• 删除动态紧急端点：DELETE /dynamic_emergency_endpoints/{id}。

语音信箱

• 获取语音信箱设置：GET /phone_numbers/{phone_number_id}/voicemail，返回 enabled（boolean）、pin（string）。
• 创建语音信箱设置：POST /phone_numbers/{phone_number_id}/voicemail，可选参数 enabled、pin。
• 更新语音信箱设置：PATCH /phone_numbers/{phone_number_id}/voicemail，可选参数 enabled、pin。

使用方式

该技能以 Java 代码示例形式提供，开发者需先安装 Telnyx Java SDK 6.89.0，初始化 TelnyxClient，然后按需调用对应模块的方法。示例中展示了参数构建方式（如使用 builder 模式）以及返回对象的字段。对于列表接口，可使用自动分页或手动分页。

适用场景

适用于需要在 Java 应用中管理 Telnyx 电话号码服务的开发者，例如：配置号码语音信箱、调整美国或非美国区域的并发语音通道容量、查询使用 Channel Billing 的号码、管理 E911 动态紧急地址与端点等。

限制

文档未提供关于收费、价格、平台兼容性、性能效果或具体使用步骤的额外说明。部分接口的完整参数与返回字段以文档所列内容为准，未列出的信息暂未提供。