<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Voice Streaming - 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).

Forking start

Call forking allows you to stream the media from a call to a specific target in realtime. This stream can be used to enable realtime audio analysis to support a variety of use cases, including fraud detection, or the creation of AI-generated audio responses. Requests must specify either the target attribute or the rx and tx attributes.

POST /calls/{callcontrolid}/actions/fork_start

Optional: clientstate (string), commandid (string), rx (string), stream_type (enum: decrypted), tx (string)

response = client.calls.actions.start_forking("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns: result (string)

Forking stop

Stop forking a call. Expected Webhooks:

• call.fork.stopped

POST /calls/{callcontrolid}/actions/fork_stop

Optional: clientstate (string), commandid (string), stream_type (enum: raw, decrypted)

response = client.calls.actions.stop_forking("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns: result (string)

Streaming start

Start streaming the media from a call to a specific WebSocket address or Dialogflow connection in near-realtime. Audio will be delivered as base64-encoded RTP payload (raw audio), wrapped in JSON payloads. Please find more details about media streaming messages specification under the link.

POST /calls/{callcontrolid}/actions/streaming_start

Optional: clientstate (string), commandid (string), customparameters (array[object]), dialogflowconfig (object), enabledialogflow (boolean), streamauthtoken (string), streambidirectionalcodec (enum: PCMU, PCMA, G722, OPUS, AMR-WB, L16), streambidirectionalmode (enum: mp3, rtp), streambidirectionalsamplingrate (enum: 8000, 16000, 22050, 24000, 48000), streambidirectionaltargetlegs (enum: both, self, opposite), streamcodec (enum: PCMU, PCMA, G722, OPUS, AMR-WB, L16, default), streamtrack (enum: inboundtrack, outboundtrack, bothtracks), stream_url (string)

response = client.calls.actions.start_streaming("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns: result (string)

Streaming stop

Stop streaming a call to a WebSocket. Expected Webhooks:

• streaming.stopped

POST /calls/{callcontrolid}/actions/streaming_stop

Optional: clientstate (string), commandid (string), stream_id (uuid)

response = client.calls.actions.stop_streaming("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns: result (string)

Transcription start

Start real-time transcription. Transcription will stop on call hang-up, or can be initiated via the Transcription stop command. Expected Webhooks:

• call.transcription

POST /calls/{callcontrolid}/actions/transcription_start

Optional: clientstate (string), commandid (string), transcriptionengine (enum: Google, Telnyx, Deepgram, Azure, xAI, AssemblyAI, Speechmatics, Soniox, Parakeet, A, B), transcriptionengineconfig (object), transcriptiontracks (string)

response = client.calls.actions.start_transcription("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

puts(response)

Returns: result (string)

Transcription stop

Stop real-time transcription.

POST /calls/{callcontrolid}/actions/transcription_stop

Optional: clientstate (string), commandid (string)

response = client.calls.actions.stop_transcription("v3:550e8400-e29b-41d4-a716-446655440000_gRU1OGRkYQ")

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.

Webhook payload fields

callForkStarted

callForkStopped

callStreamingFailed

callStreamingStarted

callStreamingStopped

transcription