telnyx-numbers-config-java

Telnyx Numbers Config - Java 是一个面向 Java 开发者的技能，用于通过 Telnyx Java SDK 配置和管理电话号码相关设置。该技能以 Java 代码示例的形式，展示如何调用 Telnyx API 完成号码配置、查询与批量操作。

用途

该技能主要用于配置电话号码设置，包括主叫号码显示（caller ID）、呼叫转移、消息功能启用以及连接分配等。它提供 Java SDK 示例，帮助开发者在 Java 项目中集成 Telnyx 的电话号码管理能力。

安装与初始化

通过 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();

主要能力

技能示例覆盖以下 API 操作：

批量更新电话号码的消息配置（POST /messaging_numbers_bulk_updates），必填 messaging_profile_id 与 numbers，可选 assign_only。
查询批量更新状态（GET /messaging_numbers_bulk_updates/{order_id}）。
列出带消息设置的移动电话号码（GET /mobile_phone_numbers/messaging）及检索单个号码（GET /mobile_phone_numbers/{id}/messaging）。
列出电话号码（GET /phone_numbers），返回字段包括 call_forwarding_enabled、call_recording_enabled、caller_id_name_enabled、connection_id、messaging_profile_id、emergency_enabled、status 等。
验证电话号码归属（POST /phone_numbers/actions/verify_ownership），返回 found、not_found 等。
列出电话号码任务（GET /phone_numbers/jobs）。
批量删除号码（POST /phone_numbers/jobs/delete_phone_numbers），每次最多一千个号码。
批量更新紧急设置（POST /phone_numbers/jobs/update_emergency_settings），必填 emergency_enabled、phone_numbers，可选 emergency_address_id。
批量更新号码（POST /phone_numbers/jobs/update_phone_numbers），可选 billing_group_id、connection_id、customer_reference、deletion_lock_enabled、external_pin、hd_voice_enabled、tags、voice 等。
检索电话号码任务（GET /phone_numbers/jobs/{id}）。
列出带消息设置的电话号码（GET /phone_numbers/messaging）。
精简列出电话号码（GET /phone_numbers/slim），性能更高、速率限制更宽松。
列出带语音设置的电话号码（GET /phone_numbers/voice）。
检索单个电话号码（GET /phone_numbers/{id}）。

使用方式

所有示例假设 client 已按上述方式初始化。电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀与国家代码，不能包含空格、短横线或括号。

分页方面，列表方法返回一页数据，可使用 .autoPager() 自动迭代：

for (var item : page.autoPager()) { ... }

也可手动控制，使用 .hasNextPage() 与 .nextPage()。

错误处理

所有 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) {
        Thread.sleep(1000);
    }
}

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

适用场景

适用于需要在 Java 应用中管理 Telnyx 电话号码的开发者，例如批量配置消息档案、更新紧急设置、查询号码语音与消息设置、验证号码归属、批量删除号码等场景。

限制

批量操作每次最多处理一千个号码。批量更新号码时至少需提交一个可更新字段。电话号码必须为 E.164 格式。关于收费、价格、平台支持范围等更多信息，资料中暂未提供。