telnyx-voice-gather-ruby
npx skills add https://github.com/team-telnyx/telnyx-ext-agent-skills --skill telnyx-voice-gather-ruby
Agent 安装分布
Skill 文档
Telnyx Voice Gather – Ruby
Installation
gem install telnyx
Setup
require "telnyx"
client = Telnyx::Client.new(
api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)
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])
response = client.calls.actions.add_ai_assistant_messages("call_control_id")
puts(response)
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)
response = client.calls.actions.start_ai_assistant("call_control_id")
puts(response)
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)
response = client.calls.actions.stop_ai_assistant("call_control_id")
puts(response)
Gather stop
Stop current gather.
POST /calls/{call_control_id}/actions/gather_stop
Optional: client_state (string), command_id (string)
response = client.calls.actions.stop_gather("call_control_id")
puts(response)
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)
response = client.calls.actions.gather_using_ai(
"call_control_id",
parameters: {properties: "bar", required: "bar", type: "bar"}
)
puts(response)
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)
response = client.calls.actions.gather_using_audio("call_control_id")
puts(response)
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)
response = client.calls.actions.gather_using_speak("call_control_id", payload: "say this on call", voice: "male")
puts(response)
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)
response = client.calls.actions.gather("call_control_id")
puts(response)
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. |