telnyx-sip-integrations-java

用途

该技能面向在 Java 项目中集成 Telnyx SIP 中继相关能力的开发者，提供基于 Telnyx Java SDK 的示例代码，涵盖自定义存储凭据、Dialogflow 连接以及外部连接等管理操作。

安装与初始化

可通过 Maven 或 Gradle 引入依赖：

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

以下示例均假定客户端已按上述方式初始化。

主要能力

自定义存储凭据管理

查询存储凭据：GET /custom_storage_credentials/{connection_id}，返回 backend（枚举：gcs、s3、azure）与 configuration。
创建存储凭据：POST /custom_storage_credentials/{connection_id}，返回 backend 与 configuration。
更新存储凭据：PUT /custom_storage_credentials/{connection_id}，返回 backend 与 configuration。
删除存储凭据：DELETE /custom_storage_credentials/{connection_id}。

Dialogflow 连接管理

查询 Dialogflow 连接：GET /dialogflow_connections/{connection_id}，返回 connection_id、conversation_profile_id、environment、record_type、service_account。
创建 Dialogflow 连接：POST /dialogflow_connections/{connection_id}，保存 Dialogflow 凭据供其他 Telnyx 服务使用。
更新 Dialogflow 连接：PUT /dialogflow_connections/{connection_id}。
删除 Dialogflow 连接：DELETE /dialogflow_connections/{connection_id}。

外部连接管理

外部连接用于通过 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、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。
详情：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。

公民地址与位置

列出 Microsoft Teams 的公民地址与位置：GET /external_connections/{id}/civic_addresses，返回 city_or_town、city_or_town_alias、company_name、country 等。

使用方式

所有 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()。

适用场景

适用于需要在 Java 应用中对接 Telnyx SIP 中继、配置外部语音集成、管理呼叫录音与媒体存储、集成 Google Dialogflow 或查询 Microsoft Teams 公民地址的开发和运维场景。

限制

资料未提供具体收费、价格、平台兼容性、性能指标或效果说明。删除外部连接可能受使用状态限制，Operator Connect 集成的移除需联系 Telnyx 支持。