From telnyx
Provides Java SDK examples for Telnyx voice streaming: real-time call audio forking to external targets, live transcription, for analytics and AI integrations.
npx claudepluginhub team-telnyx/ai --plugin telnyxThis skill uses the workspace's default tool permissions.
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
Provides Java SDK examples for Telnyx voice streaming: real-time call audio forking to external targets, live transcription, for analytics and AI integrations.
Streams Telnyx call audio in real-time, forks media to external targets, and enables live transcription using JavaScript SDK for analytics and AI.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Share bugs, ideas, or general feedback.
<!-- 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();
All examples below assume client is already initialized as shown above.
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).
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)
Stop forking a call. Expected Webhooks:
call.fork.stoppedPOST /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)
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)
Stop streaming a call to a WebSocket. Expected Webhooks:
streaming.stoppedPOST /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)
Start real-time transcription. Transcription will stop on call hang-up, or can be initiated via the Transcription stop command. Expected Webhooks:
call.transcriptionPOST /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)
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)
Stop real-time transcription.
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)
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.
| Event | Description |
|---|---|
callForkStarted | Call Fork Started |
callForkStopped | Call Fork Stopped |
callStreamingFailed | Call Streaming Failed |
callStreamingStarted | Call Streaming Started |
callStreamingStopped | Call Streaming Stopped |
transcription | Transcription |
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. |