用途
Telnyx Voice - Java 是 Telnyx 面向 Java 开发者的语音呼叫控制 SDK 技能，用于以编程方式控制电话呼叫。它覆盖外呼、呼入应答、转接、桥接、挂断、拒接、DTMF 采集、音频流传输等呼叫控制能力，并通过 webhook 接收实时呼叫事件。
安装与初始化
Maven 依赖：
<dependency>
<groupId>com.telnyx.sdk</groupId>
<artifactId>telnyx</artifactId>
<version>6.82.0</version>
</dependency>
Gradle 依赖：
implementation("com.telnyx.sdk:telnyx:6.82.0")
初始化客户端：
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
TelnyxClient client = TelnyxOkHttpClient.fromEnv();
主要能力
- 外呼：
client.calls().dial()（POST /calls），必填参数为to、from、connectionId，返回callControlId、callLegId、callSessionId、isAlive、recordingId、callDuration等字段。 - 应答呼入：
client.calls().actions().answer()（POST /calls/{call_control_id}/actions/answer）。 - 转接通话：
client.calls().actions().transfer()（POST /calls/{call_control_id}/actions/transfer），必填to与callControlId。 - 挂断：
client.calls().actions().hangup()。 - 桥接通话：
client.calls().actions().bridge()。 - 拒接：
client.calls().actions().reject()，cause可选 CALL_REJECTED 或 USER_BUSY。 - 查询通话状态：
client.calls().retrieveStatus()（GET /calls/{call_control_id}）。 - 列出连接下的活跃通话：
client.connections().listActiveCalls()（GET /connections/{connection_id}/active_calls）。 - 呼叫控制应用管理：
client.callControlApplications()的 list、create、retrieve、update、delete。
使用方式
电话号码必须为 E.164 格式（如 +13125550001），包含 + 前缀与国家代码，不含空格、短横线或括号。列表方法返回分页对象，可用 .autoPager() 自动遍历，或用 .hasNextPage() 与 .nextPage() 手动控制。所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）失败，生产代码需处理错误；常见错误码包括 401 无效 API key、403 权限不足、404 资源未找到、422 校验错误、429 限流（建议指数退避重试）。
呼叫控制是事件驱动的：调用 dial() 或收到呼入 webhook 后，需在 webhook 处理器中使用事件负载中的 call_control_id 发出后续命令。外呼与呼入流程不同：外呼以 dial() 开始，呼入必须先通过 incoming webhook 应答后才能执行其他命令。真实呼叫控制需要可公网访问的 webhook 端点，否则通话可能接通但应用无法驱动实时通话状态。
Webhook 使用 Ed25519 签名，每个请求包含 telnyx-signature-ed25519 与 telnyx-timestamp 头，生产环境必须验证签名。示例（Spring，使用原始 body）：
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");
}
}
适用场景
适用于需要在 Java 应用中构建呼叫控制流程的场景，例如外呼、呼入应答、通话转接与桥接、DTMF 采集、音频流处理，以及基于 webhook 的实时呼叫事件处理。
限制与注意事项
不要臆造 Telnyx 参数、枚举、响应字段或 webhook 字段。若所需参数、枚举或响应字段未在技能内联展示，应先阅读 references/api-details.md 再编写代码。使用“Additional Operations”中的操作前，需先阅读可选参数与响应 schema 章节；读取或匹配内联示例之外的 webhook 字段前，需先阅读 webhook payload 参考。