Telnyx Voice Advanced - 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.
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:
begin result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello") rescue Telnyx::Errors::APIConnectionError puts "Network error — check connectivity and retry" rescue Telnyx::Errors::RateLimitError
429: rate limited — wait and retry with exponential backoff
sleep(1) # Check Retry-After header for actual delay rescue Telnyx::Errors::APIStatusError => e puts "API error #{e.status}: #{e.message}" if e.status == 422 puts "Validation error — check required fields and formats" end end
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).
Update client state
Updates client state
PUT /calls/{call_control_id}/actions/client_state_update — Required: client_state
response = client.calls.actions.update_client_state("call_control_id", client_state: "aGF2ZSBhIG5pY2UgZGF5ID1d")
puts(response)
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)
response = client.calls.actions.send_dtmf("call_control_id", digits: "1www2WABCDw9")
puts(response)
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)
response = client.calls.actions.start_siprec("call_control_id")
puts(response)
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)
response = client.calls.actions.stop_siprec("call_control_id")
puts(response)
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), noise_suppression_engine_config (object)
response = client.calls.actions.start_noise_suppression("call_control_id")
puts(response)
Returns: result (string)
Noise Suppression Stop (BETA)
POST /calls/{call_control_id}/actions/suppression_stop
Optional: client_state (string), command_id (string)
response = client.calls.actions.stop_noise_suppression("call_control_id")
puts(response)
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
response = client.calls.actions.switch_supervisor_role("call_control_id", role: :barge)
puts(response)
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:
In your webhook handler (e.g., Sinatra — use raw body):
post "/webhooks" do payload = request.body.read headers = { "telnyx-signature-ed25519" => request.env["HTTP_TELNYX_SIGNATURE_ED25519"], "telnyx-timestamp" => request.env["HTTP_TELNYX_TIMESTAMP"], } begin event = client.webhooks.unwrap(payload, headers) rescue => e halt 400, "Invalid signature: #{e.message}" end
Signature valid — event is the parsed webhook payload
puts "Received event: #{event.data.event_type}" status 200 end
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.