telnyx-voice-advanced-java（telnyx voice 高级 Java）

Telnyx Voice Advanced - Java

Installation

<!-- 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")

Setup

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

All examples below assume client is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

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

Common error codes: 401 invalid API key, 403 insufficient permissions, 404 resource not found, 422 validation error (check field formats), 429 rate limited (retry with exponential backoff).

Join AI Assistant Conversation

Add a participant to an existing AI assistant conversation. Use this command to bring an additional call leg into a running AI conversation.

POST /calls/{call_control_id}/actions/ai_assistant_join — Required: conversation_id, participant

Optional: client_state (string), command_id (string)

import com.telnyx.sdk.models.calls.actions.ActionJoinAiAssistantParams;
import com.telnyx.sdk.models.calls.actions.ActionJoinAiAssistantResponse;

ActionJoinAiAssistantParams params = ActionJoinAiAssistantParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .conversationId("v3:abc123")
    .participant(ActionJoinAiAssistantParams.Participant.builder()
        .id("v3:abc123def456")
        .role(ActionJoinAiAssistantParams.Participant.Role.USER)
        .build())
    .build();
ActionJoinAiAssistantResponse response = client.calls().actions().joinAiAssistant(params);

Returns: conversation_id (uuid), result (string)

Update client state

Updates client state

PUT /calls/{call_control_id}/actions/client_state_update — Required: client_state

import com.telnyx.sdk.models.calls.actions.ActionUpdateClientStateParams;
import com.telnyx.sdk.models.calls.actions.ActionUpdateClientStateResponse;

ActionUpdateClientStateParams params = ActionUpdateClientStateParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .clientState("aGF2ZSBhIG5pY2UgZGF5ID1d")
    .build();
ActionUpdateClientStateResponse response = client.calls().actions().updateClientState(params);

Returns: result (string)

Send DTMF

Sends DTMF tones from this leg. DTMF tones will be heard by the other end of the call. Expected Webhooks:

There are no webhooks associated with this command.

POST /calls/{call_control_id}/actions/send_dtmf — Required: digits

Optional: client_state (string), command_id (string), duration_millis (int32)

import com.telnyx.sdk.models.calls.actions.ActionSendDtmfParams;
import com.telnyx.sdk.models.calls.actions.ActionSendDtmfResponse;

ActionSendDtmfParams params = ActionSendDtmfParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .digits("1www2WABCDw9")
    .build();
ActionSendDtmfResponse response = client.calls().actions().sendDtmf(params);

Returns: result (string)

SIPREC start

Start siprec session to configured in SIPREC connector SRS.

Expected Webhooks:

• siprec.started
• siprec.stopped
• siprec.failed

POST /calls/{call_control_id}/actions/siprec_start

Optional: client_state (string), connector_name (string), include_metadata_custom_headers (boolean), secure (boolean), session_timeout_secs (integer), sip_transport (enum: udp, tcp, tls), siprec_track (enum: inbound_track, outbound_track, both_tracks)

import com.telnyx.sdk.models.calls.actions.ActionStartSiprecParams;
import com.telnyx.sdk.models.calls.actions.ActionStartSiprecResponse;

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

Returns: result (string)

SIPREC stop

Stop SIPREC session. Expected Webhooks:

• siprec.stopped

POST /calls/{call_control_id}/actions/siprec_stop

Optional: client_state (string), command_id (string)

import com.telnyx.sdk.models.calls.actions.ActionStopSiprecParams;
import com.telnyx.sdk.models.calls.actions.ActionStopSiprecResponse;

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

Returns: result (string)

Noise Suppression Start (BETA)

POST /calls/{call_control_id}/actions/suppression_start

Optional: client_state (string), command_id (string), direction (enum: inbound, outbound, both), noise_suppression_engine (enum: Denoiser, DeepFilterNet, Krisp, AiCoustics), noise_suppression_engine_config (object)

import com.telnyx.sdk.models.calls.actions.ActionStartNoiseSuppressionParams;
import com.telnyx.sdk.models.calls.actions.ActionStartNoiseSuppressionResponse;

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

Returns: result (string)

Noise Suppression Stop (BETA)

POST /calls/{call_control_id}/actions/suppression_stop

Optional: client_state (string), command_id (string)

import com.telnyx.sdk.models.calls.actions.ActionStopNoiseSuppressionParams;
import com.telnyx.sdk.models.calls.actions.ActionStopNoiseSuppressionResponse;

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

Returns: result (string)

Switch supervisor role

Switch the supervisor role for a bridged call. This allows switching between different supervisor modes during an active call

POST /calls/{call_control_id}/actions/switch_supervisor_role — Required: role

import com.telnyx.sdk.models.calls.actions.ActionSwitchSupervisorRoleParams;
import com.telnyx.sdk.models.calls.actions.ActionSwitchSupervisorRoleResponse;

ActionSwitchSupervisorRoleParams params = ActionSwitchSupervisorRoleParams.builder()
    .callControlId("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")
    .role(ActionSwitchSupervisorRoleParams.Role.BARGE)
    .build();
ActionSwitchSupervisorRoleResponse response = client.calls().actions().switchSupervisorRole(params);

Returns: result (string)

Webhooks

Webhook Verification

Telnyx signs webhooks with Ed25519. Each request includes telnyx-signature-ed25519 and telnyx-timestamp headers. Always verify signatures in production:

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

// In your webhook handler (e.g., Spring — use raw body):
@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());
    // Signature valid — process the event
    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");
  }
}

The following webhook events are sent to your configured webhook URL. All webhooks include telnyx-timestamp and telnyx-signature-ed25519 headers for Ed25519 signature verification. Use client.webhooks.unwrap() to verify.

Webhook payload fields

callConversationEnded

callConversationInsightsGenerated

callDtmfReceived

callMachineDetectionEnded

callMachineGreetingEnded

callMachinePremiumDetectionEnded

callMachinePremiumGreetingEnded

callReferCompleted

callReferFailed

callReferStarted

callSiprecFailed

callSiprecStarted

callSiprecStopped