telnyx-voice-gather-java

用途

Telnyx Voice Gather - Java 是 Telnyx 官方 Java SDK 中面向语音采集（Gather）场景的技能，用于在通话过程中采集呼叫者的 DTMF 按键输入或语音输入。它可用于构建交互式语音菜单（IVR）以及 AI 语音助手，让程序在电话通话中获取用户的选择或结构化信息。

主要能力

该技能覆盖以下几类采集与助手操作：

Gather（标准 DTMF 采集）：采集 DTMF 信号以构建交互式菜单，可传入有效数字列表。调用前必须先执行 Answer 命令。对应接口 POST /calls/{call_control_id}/actions/gather。
Gather stop：停止当前采集，会触发 call.gather.ended Webhook。对应接口 POST /calls/{call_control_id}/actions/gather_stop。
Gather using audio：在通话中播放音频文件，直到采集到所需 DTMF 信号。可传入有效数字列表以及 invalid_audio_url，在每次提示开始时播放；收到 DTMF 信号时播放会被打断。对应接口 POST /calls/{call_control_id}/actions/gather_using_audio。
Gather using speak：将文本转换为语音并在通话中播放，直到采集到所需 DTMF 信号。可传入有效数字列表以及 invalid_payload，在每次提示开始时播放；收到 DTMF 信号时语音会被打断。必填参数为 voice 和 payload。对应接口 POST /calls/{call_control_id}/actions/gather_using_speak。
Gather using AI：使用语音助手采集请求负载中定义的参数。可传入以 JSON Schema 对象描述的 parameters，语音助手会尝试采集这些信息。必填参数为 parameters。对应接口 POST /calls/{call_control_id}/actions/gather_using_ai。
AI Assistant 相关操作：包括向 AI 助手发起的对话添加消息（ai_assistant_add_messages）、启动 AI 助手（ai_assistant_start）、停止 AI 助手（ai_assistant_stop）。

安装与初始化

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

使用方式

以标准 Gather 为例：

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

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

以 Gather using speak 为例：

import com.telnyx.sdk.models.calls.actions.ActionGatherUsingSpeakParams;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingSpeakResponse;

ActionGatherUsingSpeakParams params = ActionGatherUsingSpeakParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .payload("say this on call")
    .voice("male")
    .build();
ActionGatherUsingSpeakResponse response = client.calls().actions().gatherUsingSpeak(params);

以 Gather using AI 为例：

import com.telnyx.sdk.core.JsonValue;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingAiParams;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingAiResponse;

ActionGatherUsingAiParams params = ActionGatherUsingAiParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .parameters(ActionGatherUsingAiParams.Parameters.builder()
        .putAdditionalProperty("properties", JsonValue.from("bar"))
        .putAdditionalProperty("required", JsonValue.from("bar"))
        .putAdditionalProperty("type", JsonValue.from("bar"))
        .build())
    .build();
ActionGatherUsingAiResponse response = client.calls().actions().gatherUsingAi(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 key，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");
  }
}

适用场景

构建电话交互式语音菜单（IVR），通过 DTMF 按键获取用户选择。
在通话中播放音频或 TTS 提示并采集按键输入。
使用 AI 语音助手采集结构化信息（如按 JSON Schema 定义的字段）。
构建 AI 语音助手对话流程，并处理采集结果与消息历史。

限制与注意事项

标准 Gather 命令必须在 Answer 命令之后执行。
所有 API 调用需处理网络错误、401/403/404/422/429 等错误码。
生产环境必须验证 Webhook 的 Ed25519 签名。
关于计费、价格、平台支持范围等具体信息，资料中暂未提供。