<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Voice Streaming - Java

Installation

<!-- Maven -->
<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.95.0</version>
</dependency>

// Gradle
implementation("com.telnyx.sdk:telnyx:6.95.0")

Setup

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

// fromEnv() reads TELNYX_API_KEY and TELNYX_PUBLIC_KEY (the public key is required for
// client.webhooks().unwrap() — webhook verification)
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, then retry the request (bounded exponential backoff)
        Thread.sleep(1000);
        // ...retry the call here (give up after a few attempts)
    }
    throw e; // Re-throw: a failed request must never look like success to the caller
}

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).

Forking start

Call forking allows you to stream the media from a call to a specific target in realtime. This stream can be used to enable realtime audio analysis to support a variety of use cases, including fraud detection, or the creation of AI-generated audio responses. Requests must specify either the target attribute or the rx and tx attributes.

POST /calls/{call_control_id}/actions/fork_start

Optional: client_state (string), command_id (string), rx (string), stream_type (enum: decrypted), tx (string)

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

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

Returns: result (string)

Forking stop

Stop forking a call. Expected Webhooks:

• call.fork.stopped

POST /calls/{call_control_id}/actions/fork_stop

Optional: client_state (string), command_id (string), stream_type (enum: raw, decrypted)

import com.telnyx.sdk.models.calls.actions.ActionStopForkingParams;
import com.telnyx.sdk.models.calls.actions.ActionStopForkingResponse;

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

Returns: result (string)

Streaming start

Start streaming the media from a call to a specific WebSocket address or Dialogflow connection in near-realtime. Audio will be delivered as base64-encoded RTP payload (raw audio), wrapped in JSON payloads. Please find more details about media streaming messages specification under the link.

POST /calls/{call_control_id}/actions/streaming_start

Optional: client_state (string), command_id (string), custom_parameters (array[object]), dialogflow_config (object), enable_dialogflow (boolean), stream_auth_token (string), stream_bidirectional_codec (enum: PCMU, PCMA, G722, OPUS, AMR-WB, L16), stream_bidirectional_mode (enum: mp3, rtp), stream_bidirectional_sampling_rate (enum: 8000, 16000, 22050, 24000, 48000), stream_bidirectional_target_legs (enum: both, self, opposite), stream_codec (enum: PCMU, PCMA, G722, OPUS, AMR-WB, L16, default), stream_track (enum: inbound_track, outbound_track, both_tracks), stream_url (string)

import com.telnyx.sdk.models.calls.actions.ActionStartStreamingParams;
import com.telnyx.sdk.models.calls.actions.ActionStartStreamingResponse;

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

Returns: result (string)

Streaming stop

Stop streaming a call to a WebSocket. Expected Webhooks:

• streaming.stopped

POST /calls/{call_control_id}/actions/streaming_stop

Optional: client_state (string), command_id (string), stream_id (uuid)

import com.telnyx.sdk.models.calls.actions.ActionStopStreamingParams;
import com.telnyx.sdk.models.calls.actions.ActionStopStreamingResponse;

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

Returns: result (string)

Transcription start

Start real-time transcription. Transcription will stop on call hang-up, or can be initiated via the Transcription stop command. Expected Webhooks:

• call.transcription

POST /calls/{call_control_id}/actions/transcription_start

Optional: client_state (string), command_id (string), transcription_engine (enum: Google, Telnyx, Deepgram, Azure, xAI, AssemblyAI, Speechmatics, Soniox, Parakeet, Humain, Reson8, Cohere, A, B), transcription_engine_config (object), transcription_tracks (string)

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

Returns: result (string)

Transcription stop

Stops real-time transcription on the call. Transcription webhooks cease once the command takes effect; the call itself is unaffected.

POST /calls/{call_control_id}/actions/transcription_stop

Optional: client_state (string), command_id (string)

import com.telnyx.sdk.models.calls.actions.ActionStopTranscriptionParams;
import com.telnyx.sdk.models.calls.actions.ActionStopTranscriptionResponse;

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

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:

Verification needs your account's public key (Mission Control Portal → API Keys → Public Key). The SDK reads it from TELNYX_PUBLIC_KEY (the ## Setup block above passes it explicitly); without it every valid webhook fails verification and the handler below returns 400.

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.

Event	Description
callForkStarted	Call Fork Started
callForkStopped	Call Fork Stopped
callStreamingFailed	Call Streaming Failed
callStreamingStarted	Call Streaming Started
callStreamingStopped	Call Streaming Stopped
transcription	Transcription

Webhook payload fields

callForkStarted

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.fork.started	The type of event being delivered.
data.id	uuid	Identifies the type of resource.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.payload.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_control_id	string	Unique ID for controlling the call.
data.payload.call_leg_id	string	ID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id	string	ID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state	string	State received from a command.
data.payload.stream_type	enum: decrypted	Type of media streamed.

callForkStopped

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.fork.stopped	The type of event being delivered.
data.id	uuid	Identifies the type of resource.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.payload.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_control_id	string	Unique ID for controlling the call.
data.payload.call_leg_id	string	ID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id	string	ID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state	string	State received from a command.
data.payload.stream_type	enum: decrypted	Type of media streamed.

callStreamingFailed

Field	Type	Description
data.record_type	enum: event	Identifies the resource.
data.event_type	enum: streaming.failed	The type of event being delivered.
data.id	uuid	Identifies the type of resource.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.payload.call_control_id	string	Call ID used to issue commands via Call Control API.
data.payload.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_id	string	ID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id	string	ID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state	string	State received from a command.
data.payload.failure_reason	string	A short description explaning why the media streaming failed.
data.payload.stream_id	uuid	Identifies the streaming.
data.payload.stream_type	enum: websocket, dialogflow	The type of stream connection the stream is performing.

callStreamingStarted

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: streaming.started	The type of event being delivered.
data.id	uuid	Identifies the type of resource.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.payload.call_control_id	string	Call ID used to issue commands via Call Control API.
data.payload.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_id	string	ID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id	string	ID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state	string	State received from a command.
data.payload.stream_url	string	Destination WebSocket address where the stream is going to be delivered.

callStreamingStopped

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: streaming.stopped	The type of event being delivered.
data.id	uuid	Identifies the type of resource.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.payload.call_control_id	string	Call ID used to issue commands via Call Control API.
data.payload.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
data.payload.call_leg_id	string	ID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id	string	ID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state	string	State received from a command.
data.payload.stream_url	string	Destination WebSocket address where the stream is going to be delivered.

transcription

Field	Type	Description
data.record_type	enum: event	Identifies the type of the resource.
data.event_type	enum: call.transcription	The type of event being delivered.
data.id	uuid	Identifies the type of resource.
data.occurred_at	date-time	ISO 8601 datetime of when the event occurred.
data.payload.call_control_id	string	Unique identifier and token for controlling the call.
data.payload.call_leg_id	string	ID that is unique to the call and can be used to correlate webhook events.
data.payload.call_session_id	string	ID that is unique to the call session and can be used to correlate webhook events.
data.payload.client_state	string	Use this field to add state to every subsequent webhook.
data.payload.connection_id	string	Call Control App ID (formerly Telnyx connection ID) used in the call.