telnyx-voice-streaming-java

用途

Telnyx Voice Streaming - Java 用于在 Java 应用中实时处理通话音频。它允许开发者将通话媒体流分叉到外部目标、把音频流式传输到指定 WebSocket 地址或 Dialogflow 连接，并对通话进行实时转写。官方说明其典型用途包括实时音频分析、欺诈检测，以及构建 AI 生成的语音响应。

安装与初始化

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

主要能力

通话分叉（Forking）

分叉可将通话媒体实时流式传输到指定目标，用于实时音频分析等场景。请求必须指定 target 属性，或同时指定 rx 与 tx 属性。

启动分叉：POST /calls/{call_control_id}/actions/fork_start，可选参数包括 client_state、command_id、rx、stream_type（decrypted）、tx。
停止分叉：POST /calls/{call_control_id}/actions/fork_stop，可选参数包括 client_state、command_id、stream_type（raw、decrypted）。预期 Webhook 为 call.fork.stopped。

流式传输（Streaming）

将近乎实时的通话媒体流式传输到指定 WebSocket 地址或 Dialogflow 连接。音频以 base64 编码的 RTP 负载（原始音频）形式，封装在 JSON 负载中传输。

启动流式传输：POST /calls/{call_control_id}/actions/streaming_start。可选参数包括 client_state、command_id、custom_parameters、dialogflow_config、enable_dialogflow、stream_auth_token、stream_bidirectional_codec（PCMU、PCMA、G722、OPUS、AMR-WB、L16）、stream_bidirectional_mode（mp3、rtp）、stream_bidirectional_sampling_rate（8000、16000、22050、24000、48000）、stream_bidirectional_target_legs（both、self、opposite）、stream_codec（PCMU、PCMA、G722、OPUS、AMR-WB、L16、default）、stream_track（inbound_track、outbound_track、both_tracks）、stream_url。
停止流式传输：POST /calls/{call_control_id}/actions/streaming_stop，可选参数包括 client_state、command_id、stream_id。预期 Webhook 为 streaming.stopped。

实时转写（Transcription）

启动实时转写，转写会在通话挂断时停止，也可通过转写停止命令主动结束。预期 Webhook 为 call.transcription。

启动转写：POST /calls/{call_control_id}/actions/transcription_start。可选参数包括 client_state、command_id、transcription_engine（Google、Telnyx、Deepgram、Azure、xAI、AssemblyAI、Speechmatics、Soniox、Parakeet、A、B）、transcription_engine_config、transcription_tracks。
停止转写：POST /calls/{call_control_id}/actions/transcription_stop，可选参数包括 client_state、command_id。

使用方式

所有操作通过已初始化的 client 调用，例如：

import com.telnyx.sdk.models.calls.actions.ActionStartForkingResponse;

ActionStartForkingResponse response = client.calls().actions().startForking("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ");

启动转写示例：

import com.telnyx.sdk.models.calls.actions.ActionStartTranscriptionParams;
import com.telnyx.sdk.models.calls.actions.ActionStartTranscriptionResponse;
import com.telnyx.sdk.models.calls.actions.TranscriptionStartRequest;

ActionStartTranscriptionParams params = ActionStartTranscriptionParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .transcriptionStartRequest(TranscriptionStartRequest.builder().build())
    .build();
ActionStartTranscriptionResponse response = client.calls().actions().startTranscription(params);

错误处理

所有 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 速率限制（建议指数退避重试）。

Webhook 验证

Telnyx 使用 Ed25519 对 Webhook 签名，每个请求包含 telnyx-signature-ed25519 与 telnyx-timestamp 头。生产环境应始终验证签名：

import com.telnyx.sdk.core.UnwrapWebhookParams;
import com.telnyx.sdk.core.http.Headers;

@PostMapping("/webhooks")
public ResponseEntity<String> handleWebhook(
    @RequestBody String payload,
    HttpServletRequest request) {
  try {
    Headers headers = Headers.builder()
        .put("telnyx-signature-ed25519", request.getHeader("telnyx-signature-ed25519"))
        .put("telnyx-timestamp", request.getHeader("telnyx-timestamp"))
        .build();
    var event = client.webhooks().unwrap(
        UnwrapWebhookParams.builder()
            .body(payload)
            .headers(headers)
            .build());
    System.out.println("Received webhook event");
    return ResponseEntity.ok("OK");
  } catch (Exception e) {
    System.err.println("Webhook verification failed: " + e.getMessage());
    return ResponseEntity.badRequest().body("Invalid signature");
  }
}

适用场景

实时音频分析
欺诈检测
构建 AI 生成的语音响应
将通话音频接入外部 WebSocket 或 Dialogflow
实时语音转写

限制

资料未提供关于计费、价格、平台兼容性、性能指标或具体使用步骤的更多信息。分叉请求必须指定 target 属性或同时指定 rx 与 tx 属性。转写会在通话挂断时自动停止。