telnyx-voice-conferencing-java

用途

telnyx-voice-conferencing-java 是面向 Java 开发者的 Telnyx 语音会议 SDK 技能，用于创建和管理电话会议、呼叫队列与多方通话会话，适合构建呼叫中心或会议类应用。

安装与初始化

Maven 依赖（版本 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();

主要能力

会议管理

创建会议：POST /conferences，必填 call_control_id、name；可选 beep_enabled、client_state、comfort_noise、duration_minutes、hold_audio_url、hold_media_name、max_participants、region、start_conference_on_create。创建后通话会自动桥接进会议。
列出会议：GET /conferences，按 expires_at 降序返回。
检索会议：GET /conferences/{id}。
结束会议：POST /conferences/{id}/actions/end，终止所有活跃参与者。
会议在所有参与者离开后或创建后 4 小时过期（与活跃人数无关）。

参会者管理

列出参会者：GET /conferences/{conference_id}/participants。
加入会议：POST /conferences/{id}/actions/join，必填 call_control_id；支持 mute、hold、supervisor_role（barge、monitor、none、whisper）、whisper_call_control_ids、end_conference_on_exit 等参数。
离开会议：POST /conferences/{id}/actions/leave，通话回到 parked 状态，预期 Webhook 为 conference.participant.left。
保持参会者：POST /conferences/{id}/actions/hold。
静音参会者：POST /conferences/{id}/actions/mute。

音频与交互

播放音频：POST /conferences/{id}/actions/play。
停止播放：POST /conferences/{id}/actions/stop。
文本转语音：POST /conferences/{id}/actions/speak，必填 payload、voice；可选 language、payload_type（text、ssml）、voice_settings。
发送 DTMF：POST /conferences/{id}/actions/send_dtmf，必填 digits。
DTMF 采集：POST /conferences/{id}/actions/gather_using_audio，必填 call_control_id，可配置音频、超时、位数等。

录音

开始录音：POST /conferences/{id}/actions/record_start，必填 format；可选 channels（single、dual）、play_beep、trim 等；预期 Webhook 为 conference.recording.saved。
暂停录音：POST /conferences/{id}/actions/record_pause。
恢复录音：POST /conferences/{id}/actions/record_resume。
停止录音：POST /conferences/{id}/actions/record_stop。

队列操作

入队：POST /calls/{call_control_id}/actions/enqueue，必填 queue_name；可选 client_state、command_id、keep_after_hangup、max_size、max_wait_time_secs。
离队：POST /calls/{call_control_id}/actions/leave_queue。

使用方式

所有 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() 自动迭代，或使用 .hasNextPage() 与 .nextPage() 手动控制。

适用场景

适用于呼叫中心、多方电话会议、带录音与 TTS 播报的会议应用，以及需要队列（排队）能力的语音业务。

限制

会议会在所有参与者离开后或创建后 4 小时过期，不受活跃人数影响。单个会议最大活跃参会人数由创建时的 max_participants 参数控制。其余计费、价格、平台支持等具体约束资料暂未提供。