Telnyx Voice Advanced - 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:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

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)

java

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

java

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)

java

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)

java

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)

java

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)

java

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)

java

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

java

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:

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
`callConversationEnded`	Call Conversation Ended
`callConversationInsightsGenerated`	Call Conversation Insights Generated
`callDtmfReceived`	Call Dtmf Received
`callMachineDetectionEnded`	Call Machine Detection Ended
`callMachineGreetingEnded`	Call Machine Greeting Ended
`callMachinePremiumDetectionEnded`	Call Machine Premium Detection Ended
`callMachinePremiumGreetingEnded`	Call Machine Premium Greeting Ended
`callReferCompleted`	Call Refer Completed
`callReferFailed`	Call Refer Failed
`callReferStarted`	Call Refer Started
`callSiprecFailed`	Call Siprec Failed
`callSiprecStarted`	Call Siprec Started
`callSiprecStopped`	Call Siprec Stopped

Webhook payload fields

callConversationEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.conversation.ended	The type of event being delivered.
`data.id`	uuid	Unique identifier for the event.
`data.occurred_at`	date-time	ISO 8601 datetime of when the event occurred.
`data.created_at`	date-time	Timestamp when the event was created in the system.
`data.payload.assistant_id`	string	Unique identifier of the assistant involved in the call.
`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 leg.
`data.payload.call_session_id`	string	ID that is unique to the call session (group of related call legs).
`data.payload.client_state`	string	Base64-encoded state received from a command.
`data.payload.calling_party_type`	enum: pstn, sip	The type of calling party connection.
`data.payload.conversation_id`	string	ID unique to the conversation or insight group generated for the call.
`data.payload.duration_sec`	integer	Duration of the conversation in seconds.
`data.payload.from`	string	The caller's number or identifier.
`data.payload.to`	string	The callee's number or SIP address.
`data.payload.llm_model`	string	The large language model used during the conversation.
`data.payload.stt_model`	string	The speech-to-text model used in the conversation.
`data.payload.tts_provider`	string	The text-to-speech provider used in the call.
`data.payload.tts_model_id`	string	The model ID used for text-to-speech synthesis.
`data.payload.tts_voice_id`	string	Voice ID used for TTS.

callConversationInsightsGenerated

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.conversation_insights.generated	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.calling_party_type`	enum: pstn, sip	The type of calling party connection.
`data.payload.insight_group_id`	string	ID that is unique to the insight group being generated for the call.
`data.payload.results`	array[object]	Array of insight results being generated for the call.

callDtmfReceived

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.dtmf.received	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	Identifies the type of resource.
`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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.digit`	string	The received DTMF digit or symbol.

callMachineDetectionEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.detection.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: human, machine, not_sure	Answering machine detection result.

callMachineGreetingEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.greeting.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: beep_detected, ended, not_sure	Answering machine greeting ended result.

callMachinePremiumDetectionEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.premium.detection.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: human_residence, human_business, machine, silence, fax_detected, not_sure	Premium Answering Machine Detection result.

callMachinePremiumGreetingEnded

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.machine.premium.greeting.ended	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.from`	string	Number or SIP URI placing the call.
`data.payload.to`	string	Destination number or SIP URI of the call.
`data.payload.result`	enum: beep_detected, no_beep_detected	Premium Answering Machine Greeting Ended result.

callReferCompleted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.refer.completed	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 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.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callReferFailed

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.refer.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	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.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callReferStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: call.refer.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	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.connection_id`	string	Call Control App ID (formerly Telnyx connection ID) used in the call.
`data.payload.client_state`	string	State received from a command.
`data.payload.from`	string	Number or SIP URI placing the call.
`data.payload.sip_notify_response`	integer	SIP NOTIFY event status for tracking the REFER attempt.
`data.payload.to`	string	Destination number or SIP URI of the call.

callSiprecFailed

Field	Type	Description
`data.record_type`	enum: event	Identifies the resource.
`data.event_type`	enum: siprec.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_cause`	string	Q850 reason why siprec session failed.

callSiprecStarted

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: siprec.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.

callSiprecStopped

Field	Type	Description
`data.record_type`	enum: event	Identifies the type of the resource.
`data.event_type`	enum: siprec.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.hangup_cause`	string	Q850 reason why the SIPREC session was stopped.

telnyx-voice-advanced-java

NPX Install

Tags

SKILL.md Content

Telnyx Voice Advanced - Java

Installation

Setup

Error Handling

Join AI Assistant Conversation

Update client state

Send DTMF

SIPREC start

SIPREC stop

Noise Suppression Start (BETA)

Noise Suppression Stop (BETA)

Switch supervisor role

Webhooks

Webhook Verification

Webhook payload fields