用途
本技能面向使用 Java 开发、需要对接 Telnyx SIP 中继与语音集成能力的场景，提供基于 Telnyx Java SDK 的示例代码。它覆盖自定义存储凭据、Dialogflow 连接、外部连接（External Connections）以及外部连接日志消息等管理操作，帮助开发者在 Java 项目中调用 Telnyx 相关 API。
安装与初始化
Maven 依赖：
<dependency>
<groupId>com.telnyx.sdk</groupId>
<artifactId>telnyx</artifactId>
<version>6.36.0</version>
</dependency>
Gradle 依赖：
implementation("com.telnyx.sdk:telnyx:6.36.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 key，403 权限不足，404 资源未找到，422 校验错误（检查字段格式），429 速率限制（使用指数退避重试）。
分页
列表方法返回一页数据。可使用 .autoPager() 自动迭代：for (var item : page.autoPager()) { ... }。如需手动控制，可使用 .hasNextPage() 与 .nextPage()。
自定义存储凭据
支持对自定义存储凭据进行查询、创建、更新和删除，后端类型包括 gcs、s3、azure。
- 查询：
GET /custom_storage_credentials/{connection_id}，返回 backend（枚举：gcs、s3、azure）与 configuration（对象）。 - 创建：
POST /custom_storage_credentials/{connection_id}，返回同上。 - 更新：
PUT /custom_storage_credentials/{connection_id}，返回同上。 - 删除：
DELETE /custom_storage_credentials/{connection_id}。
示例（创建）：
import com.telnyx.sdk.models.customstoragecredentials.CustomStorageConfiguration;
import com.telnyx.sdk.models.customstoragecredentials.CustomStorageCredentialCreateParams;
import com.telnyx.sdk.models.customstoragecredentials.CustomStorageCredentialCreateResponse;
import com.telnyx.sdk.models.customstoragecredentials.GcsConfigurationData;
CustomStorageCredentialCreateParams params = CustomStorageCredentialCreateParams.builder()
.connectionId("550e8400-e29b-41d4-a716-446655440000")
.customStorageConfiguration(CustomStorageConfiguration.builder()
.backend(CustomStorageConfiguration.Backend.GCS)
.configuration(GcsConfigurationData.builder()
.backend(GcsConfigurationData.Backend.GCS)
.build())
.build())
.build();
CustomStorageCredentialCreateResponse customStorageCredential = client.customStorageCredentials().create(params);
Dialogflow 连接
支持对与 CallControl 连接关联的 Dialogflow 连接进行查询、创建、更新和删除。
- 查询：
GET /dialogflow_connections/{connection_id}，返回 connection_id、conversation_profile_id、environment、record_type、service_account。 - 创建：
POST /dialogflow_connections/{connection_id}，将 Dialogflow 凭据保存到 Telnyx，以便与其他 Telnyx 服务配合使用。 - 更新：
PUT /dialogflow_connections/{connection_id}。 - 删除：
DELETE /dialogflow_connections/{connection_id}。
外部连接（External Connections）
外部连接用于 Telnyx 客户通过 Mission Control Portal 中的 External Voice Integrations 无缝配置与 Telnyx 合作伙伴的 SIP 中继集成。
- 列表：
GET /external_connections，返回 active、created_at、credential_active、external_sip_connection（枚举：zoom、operator_connect）、id、inbound、outbound、record_type、tags、updated_at、webhook_api_version（枚举：1、2）、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs 等字段。 - 创建：
POST /external_connections，必填 external_sip_connection 与 outbound；可选 active、inbound、tags、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs。创建后可通过 /phone_numbers 端点将电话号码分配给应用。 - 查询：
GET /external_connections/{id}。 - 更新：
PATCH /external_connections/{id}，必填 outbound；可选 active、inbound、tags、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs。 - 删除：
DELETE /external_connections/{id}。若应用正被电话号码使用、处于活动状态，或属于 Operator Connect 连接，删除可能被阻止。移除 Operator Connect 集成需联系 Telnyx 支持。
外部连接日志消息
- 列表：
GET /external_connections/log_messages，返回 log_messages（数组）与 meta（对象）。 - 查询：
GET /external_connections/log_messages/{id}，返回 log_messages（数组）。 - 忽略：
DELETE /external_connections/log_messages/{id}，返回 success（布尔值）。
市政地址与位置
GET /external_connections/{id}/civic_addresses 返回来自 Microsoft Teams 的市政地址与位置，字段包括 city_or_town、city_or_town_alias、company_name、country 等。
适用场景与限制
适用于在 Java 项目中集成 Telnyx SIP 中继、管理存储凭据、对接 Dialogflow、配置外部连接及查询日志等场景。文档未提供收费、价格、平台支持范围或性能效果等信息。