telnyx-voice-media-java

用途

telnyx-voice-media-java 是一个 Java 技能包，提供 Telnyx Voice Media 相关能力，用于在通话中播放音频、进行文本转语音（TTS）朗读以及录制通话。适用于构建 IVR 系统、播放公告、录制对话等场景。

主要能力

• 播放音频 URL：在通话中播放音频文件；连续下发多个播放命令时，音频会进入队列等待播放。注意：启用 overlay 时，target_legs 仅限 self。
• 停止音频播放：停止通话中正在播放的音频，相关 Webhook 为 call.playback.ended 或 call.speak.ended。
• 录音暂停 / 恢复：暂停或恢复通话录音，资料说明这两条命令没有关联的 Webhook。
• 录音开始 / 停止：开始录音（通话挂断时自动停止，或通过停止录音命令结束），相关 Webhook 包括 call.recording.saved、call.recording.transcription.saved、call.recording.error。
• 文本转语音（Speak）：将文本转换为语音并在通话中播放；连续多条 speak 命令同样会排队播放，相关 Webhook 为 call.speak.started、call.speak.ended。
• Webhook 事件：涵盖 callPlaybackStarted、callPlaybackEnded、callRecordingError、callRecordingSaved、callRecordingTranscriptionSaved、callSpeakStarted、callSpeakEnded，并列出各自 payload 字段。
• Webhook 签名校验：Telnyx 使用 Ed25519 对 Webhook 签名，请求包含 telnyx-signature-ed25519 与 telnyx-timestamp 头，可通过 client.webhooks().unwrap() 校验。

使用方式

安装依赖（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）而失败，生产代码应始终处理错误。常见错误码：401 无效 API key、403 权限不足、404 资源未找到、422 校验错误、429 限流（建议指数退避重试）。

命令端点与示例：

• 播放音频 URL：POST /calls/{call_control_id}/actions/playback_start，可选参数包括 audio_type（mp3、wav）、audio_url、cache_audio、client_state、command_id、loop、media_name、overlay、playback_content、stop、target_legs。
• 停止音频播放：POST /calls/{call_control_id}/actions/playback_stop，可选参数 client_state、command_id、overlay、stop。
• 录音暂停：POST /calls/{call_control_id}/actions/record_pause，可选 client_state、command_id、recording_id。
• 录音恢复：POST /calls/{call_control_id}/actions/record_resume，可选 client_state、command_id、recording_id。
• 录音开始：POST /calls/{call_control_id}/actions/record_start，必填 format、channels；可选参数包括 custom_file_name、max_length、play_beep、recording_track（both、inbound、outbound）、timeout_secs、transcription、transcription_engine、transcription_language、transcription_max_speaker_count、transcription_min_speaker_count、transcription_profanity_filter、transcription_speaker_diarization、trim（trim-silence）等。
• 录音停止：POST /calls/{call_control_id}/actions/record_stop，可选 client_state、command_id、recording_id。
• Speak 文本：POST /calls/{call_control_id}/actions/speak，必填 payload、voice；可选参数包括 language、loop、payload_type（text、ssml）、service_level（basic、premium）、stop、target_legs（self、opposite、both）、voice_settings。

资料给出了对应的 Java 示例代码，例如：

ActionStartRecordingParams params = ActionStartRecordingParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .channels(ActionStartRecordingParams.Channels.SINGLE)
    .format(ActionStartRecordingParams.Format.WAV)
    .build();
ActionStartRecordingResponse response = client.calls().actions().startRecording(params);

ActionSpeakParams params = ActionSpeakParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .payload("Say this on the call")
    .voice("female")
    .language("en-US")
    .build();
ActionSpeakResponse response = client.calls().actions().speak(params);

适用场景

• IVR 系统：通过播放音频与 speak 文本实现语音菜单与导航。
• 播放公告：向通话播放音频文件或 TTS 语音。
• 录制对话：开始/停止/暂停/恢复通话录音，并可选转写。

限制

• 启用 overlay 时，target_legs 仅限 self。
• 连续下发多条播放或 speak 命令时，音频会排队等待播放。
• 录音暂停与恢复命令没有关联的 Webhook 事件。
• 录音会在通话挂断时停止。
• 生产环境应在处理 Webhook 前验证 Ed25519 签名。
• 资料未提供价格、收费或配额信息。

暂未提供

资料未提供关于价格、计费方式、并发上限、可用区域等具体信息。