Agent skill

telnyx-voice-streaming-java

Stream call audio in real-time, fork media to external destinations, and transcribe speech live. Use for real-time analytics and AI integrations. This skill provides Java SDK examples.

View SKILL.md on GitHub Repository
Stars 167
Forks 6

Install this agent skill to your Project

npx add-skill https://github.com/team-telnyx/ai/tree/main/providers/cursor/plugin/skills/telnyx-voice-streaming-java

Metadata

Additional technical details for this skill

author
telnyx
product
voice-streaming
language
java
generated by
telnyx-ext-skills-generator

SKILL.md

Telnyx Voice Streaming - Java

Installation

text
<!-- 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

java
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:

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

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)

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

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

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

java
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, A, B), transcription_engine_config (object), transcription_tracks (string)

java
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

Stop real-time transcription.

POST /calls/{call_control_id}/actions/transcription_stop

Optional: client_state (string), command_id (string)

java
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:

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

team-telnyx/ai

telnyx-oauth-go

Implement OAuth 2.0 authentication flows for Telnyx API access. This skill provides Go SDK examples.

167 6
Explore
team-telnyx/ai

telnyx-account-access-ruby

Configure account addresses, authentication providers, IP access controls, billing groups, and integration secrets. This skill provides Ruby SDK examples.

167 6
Explore
team-telnyx/ai

telnyx-sip-curl

Configure SIP trunking connections and outbound voice profiles. Use when connecting PBX systems or managing SIP infrastructure. This skill provides REST API (curl) examples.

167 6
Explore
team-telnyx/ai

telnyx-storage-java

Manage cloud storage buckets and objects using the S3-compatible Telnyx Storage API. This skill provides Java SDK examples.

167 6
Explore
team-telnyx/ai

telnyx-voice-advanced-ruby

Advanced call control features including DTMF sending, SIPREC recording, noise suppression, client state, and supervisor controls. This skill provides Ruby SDK examples.

167 6
Explore
team-telnyx/ai

telnyx-numbers-compliance-ruby

Manage regulatory requirements, number bundles, supporting documents, and verified numbers for compliance. This skill provides Ruby SDK examples.

167 6
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results