telnyx-voice-media-ruby
npx skills add https://github.com/team-telnyx/telnyx-ext-agent-skills --skill telnyx-voice-media-ruby
Agent 安装分布
Skill 文档
Telnyx Voice Media – 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.
Play audio URL
Play an audio file on the call.
POST /calls/{call_control_id}/actions/playback_start
Optional: audio_type (enum), audio_url (string), cache_audio (boolean), client_state (string), command_id (string), loop (object), media_name (string), overlay (boolean), playback_content (string), stop (string), target_legs (string)
response = client.calls.actions.start_playback("call_control_id")
puts(response)
Stop audio playback
Stop audio being played on the call.
POST /calls/{call_control_id}/actions/playback_stop
Optional: client_state (string), command_id (string), overlay (boolean), stop (string)
response = client.calls.actions.stop_playback("call_control_id")
puts(response)
Record pause
Pause recording the call.
POST /calls/{call_control_id}/actions/record_pause
Optional: client_state (string), command_id (string), recording_id (uuid)
response = client.calls.actions.pause_recording("call_control_id")
puts(response)
Record resume
Resume recording the call.
POST /calls/{call_control_id}/actions/record_resume
Optional: client_state (string), command_id (string), recording_id (uuid)
response = client.calls.actions.resume_recording("call_control_id")
puts(response)
Recording start
Start recording the call.
POST /calls/{call_control_id}/actions/record_start â Required: format, channels
Optional: client_state (string), command_id (string), custom_file_name (string), max_length (int32), play_beep (boolean), recording_track (enum), timeout_secs (int32), transcription (boolean), transcription_engine (enum), transcription_language (enum), transcription_max_speaker_count (int32), transcription_min_speaker_count (int32), transcription_profanity_filter (boolean), transcription_speaker_diarization (boolean), trim (enum)
response = client.calls.actions.start_recording("call_control_id", channels: :single, format_: :wav)
puts(response)
Recording stop
Stop recording the call.
POST /calls/{call_control_id}/actions/record_stop
Optional: client_state (string), command_id (string), recording_id (uuid)
response = client.calls.actions.stop_recording("call_control_id")
puts(response)
Speak text
Convert text to speech and play it back on the call.
POST /calls/{call_control_id}/actions/speak â Required: payload, voice
Optional: client_state (string), command_id (string), language (enum), loop (object), payload_type (enum), service_level (enum), stop (string), target_legs (enum), voice_settings (object)
response = client.calls.actions.speak("call_control_id", payload: "Say this on the call", voice: "female")
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 |
|---|---|
callPlaybackStarted |
Call Playback Started |
callPlaybackEnded |
Call Playback Ended |
callSpeakEnded |
Call Speak Ended |
callRecordingSaved |
Call Recording Saved |
callRecordingError |
Call Recording Error |
callRecordingTranscriptionSaved |
Call Recording Transcription Saved |
callSpeakStarted |
Call Speak Started |
Webhook payload fields
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. |
callSpeakEnded
| 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.status |
enum | Reflects how the command ended. |
callRecordingSaved
| 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_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.recording_started_at |
date-time | ISO 8601 datetime of when recording started. |
data.payload.recording_ended_at |
date-time | ISO 8601 datetime of when recording ended. |
data.payload.channels |
enum | Whether recording was recorded in single or dual channel. |
callRecordingError
| 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.reason |
enum | Indication that there was a problem recording the call. |
callRecordingTranscriptionSaved
| 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.calling_party_type |
enum | The type of calling party connection. |
data.payload.recording_id |
string | ID that is unique to the recording session and can be used to correlate webhook events. |
data.payload.recording_transcription_id |
string | ID that is unique to the transcription process and can be used to correlate webhook events. |
data.payload.status |
enum | The transcription status. |
data.payload.transcription_text |
string | The transcribed text |
callSpeakStarted
| 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. |