Telnyx Voice Gather - Java

Installation

text

// See https://github.com/team-telnyx/telnyx-java for Maven/Gradle setup

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.

Add messages to AI Assistant

Add messages to the conversation started by an AI assistant on the call.

POST /calls/{call_control_id}/actions/ai_assistant_add_messages

Optional:

client_state

(string),

command_id

(string),

messages

(array[object])

java

import com.telnyx.sdk.models.calls.actions.ActionAddAiAssistantMessagesParams;
import com.telnyx.sdk.models.calls.actions.ActionAddAiAssistantMessagesResponse;

ActionAddAiAssistantMessagesResponse response = client.calls().actions().addAiAssistantMessages("call_control_id");

Start AI Assistant

Start an AI assistant on the call.

POST /calls/{call_control_id}/actions/ai_assistant_start

Optional:

assistant

(object),

client_state

(string),

command_id

(string),

greeting

(string),

interruption_settings

(object),

transcription

(object),

voice

(string),

voice_settings

(object)

java

import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantParams;
import com.telnyx.sdk.models.calls.actions.ActionStartAiAssistantResponse;

ActionStartAiAssistantResponse response = client.calls().actions().startAiAssistant("call_control_id");

Stop AI Assistant

Stop an AI assistant on the call.

POST /calls/{call_control_id}/actions/ai_assistant_stop

Optional:

client_state

(string),

command_id

(string)

java

import com.telnyx.sdk.models.calls.actions.ActionStopAiAssistantParams;
import com.telnyx.sdk.models.calls.actions.ActionStopAiAssistantResponse;

ActionStopAiAssistantResponse response = client.calls().actions().stopAiAssistant("call_control_id");

Gather stop

Stop current gather.

POST /calls/{call_control_id}/actions/gather_stop

Optional:

client_state

(string),

command_id

(string)

java

import com.telnyx.sdk.models.calls.actions.ActionStopGatherParams;
import com.telnyx.sdk.models.calls.actions.ActionStopGatherResponse;

ActionStopGatherResponse response = client.calls().actions().stopGather("call_control_id");

Gather using AI

Gather parameters defined in the request payload using a voice assistant.

POST /calls/{call_control_id}/actions/gather_using_ai

— Required:

parameters

Optional:

assistant

(object),

client_state

(string),

command_id

(string),

gather_ended_speech

(string),

greeting

(string),

interruption_settings

(object),

language

(object),

message_history

(array[object]),

send_message_history_updates

(boolean),

send_partial_results

(boolean),

transcription

(object),

user_response_timeout_ms

(integer),

voice

(string),

voice_settings

(object)

java

import com.telnyx.sdk.core.JsonValue;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingAiParams;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingAiResponse;

ActionGatherUsingAiParams params = ActionGatherUsingAiParams.builder()
    .callControlId("call_control_id")
    .parameters(ActionGatherUsingAiParams.Parameters.builder()
        .putAdditionalProperty("properties", JsonValue.from("bar"))
        .putAdditionalProperty("required", JsonValue.from("bar"))
        .putAdditionalProperty("type", JsonValue.from("bar"))
        .build())
    .build();
ActionGatherUsingAiResponse response = client.calls().actions().gatherUsingAi(params);

Gather using audio

Play an audio file on the call until the required DTMF signals are gathered to build interactive menus.

POST /calls/{call_control_id}/actions/gather_using_audio

Optional:

audio_url

(string),

client_state

(string),

command_id

(string),

inter_digit_timeout_millis

(int32),

invalid_audio_url

(string),

invalid_media_name

(string),

maximum_digits

(int32),

maximum_tries

(int32),

media_name

(string),

minimum_digits

(int32),

terminating_digit

(string),

timeout_millis

(int32),

valid_digits

(string)

java

import com.telnyx.sdk.models.calls.actions.ActionGatherUsingAudioParams;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingAudioResponse;

ActionGatherUsingAudioResponse response = client.calls().actions().gatherUsingAudio("call_control_id");

Gather using speak

Convert text to speech and play it on the call until the required DTMF signals are gathered to build interactive menus.

POST /calls/{call_control_id}/actions/gather_using_speak

— Required:

voice

payload

Optional:

client_state

(string),

command_id

(string),

inter_digit_timeout_millis

(int32),

invalid_payload

(string),

language

(enum),

maximum_digits

(int32),

maximum_tries

(int32),

minimum_digits

(int32),

payload_type

(enum),

service_level

(enum),

terminating_digit

(string),

timeout_millis

(int32),

valid_digits

(string),

voice_settings

(object)

java

import com.telnyx.sdk.models.calls.actions.ActionGatherUsingSpeakParams;
import com.telnyx.sdk.models.calls.actions.ActionGatherUsingSpeakResponse;

ActionGatherUsingSpeakParams params = ActionGatherUsingSpeakParams.builder()
    .callControlId("call_control_id")
    .payload("say this on call")
    .voice("male")
    .build();
ActionGatherUsingSpeakResponse response = client.calls().actions().gatherUsingSpeak(params);

Gather

Gather DTMF signals to build interactive menus.

POST /calls/{call_control_id}/actions/gather

Optional:

client_state

(string),

command_id

(string),

gather_id

(string),

initial_timeout_millis

(int32),

inter_digit_timeout_millis

(int32),

maximum_digits

(int32),

minimum_digits

(int32),

terminating_digit

(string),

timeout_millis

(int32),

valid_digits

(string)

java

import com.telnyx.sdk.models.calls.actions.ActionGatherParams;
import com.telnyx.sdk.models.calls.actions.ActionGatherResponse;

ActionGatherResponse response = client.calls().actions().gather("call_control_id");

Webhooks

The following webhook events are sent to your configured webhook URL. All webhooks include

telnyx-timestamp

and

telnyx-signature-ed25519

headers for verification (Standard Webhooks compatible).

Event	Description
`callGatherEnded`	Call Gather Ended
`CallAIGatherEnded`	Call AI Gather Ended
`CallAIGatherMessageHistoryUpdated`	Call AI Gather Message History Updated
`CallAIGatherPartialResults`	Call AI Gather Partial Results
`CallConversationEnded`	Call Conversation Ended
`callPlaybackStarted`	Call Playback Started
`callPlaybackEnded`	Call Playback Ended
`callDtmfReceived`	Call Dtmf Received

Webhook payload fields

callGatherEnded

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	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.digits`	string	The received DTMF digit or symbol.
`data.payload.status`	enum	Reflects how command ended.

CallAIGatherEnded

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	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	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.message_history`	array[object]	The history of the messages exchanged during the AI gather
`data.payload.result`	object	The result of the AI gather, its type depends of the `parameters` provided in the command
`data.payload.status`	enum	Reflects how command ended.

CallAIGatherMessageHistoryUpdated

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	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	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.message_history`	array[object]	The history of the messages exchanged during the AI gather

CallAIGatherPartialResults

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	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	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.message_history`	array[object]	The history of the messages exchanged during the AI gather
`data.payload.partial_results`	object	The partial result of the AI gather, its type depends of the `parameters` provided in the command

CallConversationEnded

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

callPlaybackStarted

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	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.media_url`	string	The audio URL being played back, if audio_url has been used to start.
`data.payload.media_name`	string	The name of the audio media file being played back, if media_name has been used to start.
`data.payload.overlay`	boolean	Whether the audio is going to be played in overlay mode or not.

callPlaybackEnded

Field	Type	Description
`data.record_type`	enum	Identifies the type of the resource.
`data.event_type`	enum	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.media_url`	string	The audio URL being played back, if audio_url has been used to start.
`data.payload.media_name`	string	The name of the audio media file being played back, if media_name has been used to start.
`data.payload.overlay`	boolean	Whether the stopped audio was in overlay mode or not.
`data.payload.status`	enum	Reflects how command ended.
`data.payload.status_detail`	string	Provides details in case of failure.

callDtmfReceived

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

telnyx-voice-gather-java

NPX Install

Tags

SKILL.md Content

Telnyx Voice Gather - Java

Installation

Setup

Add messages to AI Assistant

Start AI Assistant

Stop AI Assistant

Gather stop

Gather using AI

Gather using audio

Gather using speak

Gather

Webhooks

Webhook payload fields