Telnyx Video - Ruby

Installation

bash

gem install telnyx

Setup

ruby

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:

ruby

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:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

View a list of room compositions.

GET /room_compositions

ruby

page = client.room_compositions.list

puts(page)

Returns:

completed_at

(date-time),

created_at

(date-time),

download_url

(string),

duration_secs

(integer),

ended_at

(date-time),

format

(enum: mp4),

id

(uuid),

record_type

(string),

resolution

(string),

room_id

(uuid),

session_id

(uuid),

size_mb

(float),

started_at

(date-time),

status

(enum: completed, enqueued, processing),

updated_at

(date-time),

user_id

(uuid),

video_layout

(object),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

Create a room composition.

Asynchronously create a room composition.

POST /room_compositions

Optional:

format

(string),

resolution

(string),

session_id

(uuid),

video_layout

(object),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

ruby

room_composition = client.room_compositions.create

puts(room_composition)

Returns:

completed_at

(date-time),

created_at

(date-time),

download_url

(string),

duration_secs

(integer),

ended_at

(date-time),

format

(enum: mp4),

id

(uuid),

record_type

(string),

resolution

(string),

room_id

(uuid),

session_id

(uuid),

size_mb

(float),

started_at

(date-time),

status

(enum: completed, enqueued, processing),

updated_at

(date-time),

user_id

(uuid),

video_layout

(object),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

View a room composition.

GET /room_compositions/{room_composition_id}

ruby

room_composition = client.room_compositions.retrieve("5219b3af-87c6-4c08-9b58-5a533d893e21")

puts(room_composition)

Returns:

completed_at

(date-time),

created_at

(date-time),

download_url

(string),

duration_secs

(integer),

ended_at

(date-time),

format

(enum: mp4),

id

(uuid),

record_type

(string),

resolution

(string),

room_id

(uuid),

session_id

(uuid),

size_mb

(float),

started_at

(date-time),

status

(enum: completed, enqueued, processing),

updated_at

(date-time),

user_id

(uuid),

video_layout

(object),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

Delete a room composition.

Synchronously delete a room composition.

DELETE /room_compositions/{room_composition_id}

ruby

result = client.room_compositions.delete("5219b3af-87c6-4c08-9b58-5a533d893e21")

puts(result)

View a list of room participants.

GET /room_participants

ruby

page = client.room_participants.list

puts(page)

Returns:

context

(string),

id

(uuid),

joined_at

(date-time),

left_at

(date-time),

record_type

(string),

session_id

(uuid),

updated_at

(date-time)

View a room participant.

GET /room_participants/{room_participant_id}

ruby

room_participant = client.room_participants.retrieve("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(room_participant)

Returns:

context

(string),

id

(uuid),

joined_at

(date-time),

left_at

(date-time),

record_type

(string),

session_id

(uuid),

updated_at

(date-time)

View a list of room recordings.

GET /room_recordings

ruby

page = client.room_recordings.list

puts(page)

Returns:

codec

(string),

completed_at

(date-time),

created_at

(date-time),

download_url

(string),

duration_secs

(integer),

ended_at

(date-time),

id

(uuid),

participant_id

(uuid),

record_type

(string),

room_id

(uuid),

session_id

(uuid),

size_mb

(float),

started_at

(date-time),

status

(enum: completed, processing),

type

(enum: audio, video),

updated_at

(date-time)

Delete several room recordings in a bulk.

DELETE /room_recordings

ruby

response = client.room_recordings.delete_bulk

puts(response)

Returns:

room_recordings

(integer)

View a room recording.

GET /room_recordings/{room_recording_id}

ruby

room_recording = client.room_recordings.retrieve("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(room_recording)

Returns:

codec

(string),

completed_at

(date-time),

created_at

(date-time),

download_url

(string),

duration_secs

(integer),

ended_at

(date-time),

id

(uuid),

participant_id

(uuid),

record_type

(string),

room_id

(uuid),

session_id

(uuid),

size_mb

(float),

started_at

(date-time),

status

(enum: completed, processing),

type

(enum: audio, video),

updated_at

(date-time)

Delete a room recording.

Synchronously delete a Room Recording.

DELETE /room_recordings/{room_recording_id}

ruby

result = client.room_recordings.delete("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(result)

View a list of room sessions.

GET /room_sessions

ruby

page = client.rooms.sessions.list_0

puts(page)

Returns:

active

(boolean),

created_at

(date-time),

ended_at

(date-time),

id

(uuid),

participants

(array[object]),

record_type

(string),

room_id

(uuid),

updated_at

(date-time)

View a room session.

GET /room_sessions/{room_session_id}

ruby

session = client.rooms.sessions.retrieve("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(session)

Returns:

active

(boolean),

created_at

(date-time),

ended_at

(date-time),

id

(uuid),

participants

(array[object]),

record_type

(string),

room_id

(uuid),

updated_at

(date-time)

End a room session.

Note: this will also kick all participants currently present in the room

POST /room_sessions/{room_session_id}/actions/end

ruby

response = client.rooms.sessions.actions.end_("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(response)

Returns:

result

(string)

Kick participants from a room session.

POST /room_sessions/{room_session_id}/actions/kick

Optional:

exclude

(array[string]),

participants

(object)

ruby

response = client.rooms.sessions.actions.kick("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(response)

Returns:

result

(string)

Mute participants in room session.

POST /room_sessions/{room_session_id}/actions/mute

Optional:

exclude

(array[string]),

participants

(object)

ruby

response = client.rooms.sessions.actions.mute("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(response)

Returns:

result

(string)

Unmute participants in room session.

POST /room_sessions/{room_session_id}/actions/unmute

Optional:

exclude

(array[string]),

participants

(object)

ruby

response = client.rooms.sessions.actions.unmute("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(response)

Returns:

result

(string)

View a list of room participants.

GET /room_sessions/{room_session_id}/participants

ruby

page = client.rooms.sessions.retrieve_participants("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(page)

Returns:

context

(string),

id

(uuid),

joined_at

(date-time),

left_at

(date-time),

record_type

(string),

session_id

(uuid),

updated_at

(date-time)

View a list of rooms.

GET /rooms

ruby

page = client.rooms.list

puts(page)

Returns:

active_session_id

(uuid),

created_at

(date-time),

enable_recording

(boolean),

id

(uuid),

max_participants

(integer),

record_type

(string),

sessions

(array[object]),

unique_name

(string),

updated_at

(date-time),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

Create a room.

Synchronously create a Room.

POST /rooms

Optional:

enable_recording

(boolean),

max_participants

(integer),

unique_name

(string),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

ruby

room = client.rooms.create(unique_name: "my-meeting-room", max_participants: 10)
puts(room)

Returns:

active_session_id

(uuid),

created_at

(date-time),

enable_recording

(boolean),

id

(uuid),

max_participants

(integer),

record_type

(string),

sessions

(array[object]),

unique_name

(string),

updated_at

(date-time),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

View a room.

GET /rooms/{room_id}

ruby

room = client.rooms.retrieve("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(room)

Returns:

active_session_id

(uuid),

created_at

(date-time),

enable_recording

(boolean),

id

(uuid),

max_participants

(integer),

record_type

(string),

sessions

(array[object]),

unique_name

(string),

updated_at

(date-time),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

Update a room.

Synchronously update a Room.

PATCH /rooms/{room_id}

Optional:

enable_recording

(boolean),

max_participants

(integer),

unique_name

(string),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

ruby

room = client.rooms.update("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(room)

Returns:

active_session_id

(uuid),

created_at

(date-time),

enable_recording

(boolean),

id

(uuid),

max_participants

(integer),

record_type

(string),

sessions

(array[object]),

unique_name

(string),

updated_at

(date-time),

webhook_event_failover_url

(uri),

webhook_event_url

(uri),

webhook_timeout_secs

(integer)

Delete a room.

Synchronously delete a Room. Participants from that room will be kicked out, they won't be able to join that room anymore, and you won't be charged anymore for that room.

DELETE /rooms/{room_id}

ruby

result = client.rooms.delete("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(result)

Create Client Token to join a room.

Synchronously create an Client Token to join a Room. Client Token is necessary to join a Telnyx Room. Client Token will expire after

token_ttl_secs

, a Refresh Token is also provided to refresh a Client Token, the Refresh Token expires after

refresh_token_ttl_secs

POST /rooms/{room_id}/actions/generate_join_client_token

Optional:

refresh_token_ttl_secs

(integer),

token_ttl_secs

(integer)

ruby

response = client.rooms.actions.generate_join_client_token("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(response)

Returns:

refresh_token

(string),

refresh_token_expires_at

(date-time),

token

(string),

token_expires_at

(date-time)

Refresh Client Token to join a room.

Synchronously refresh an Client Token to join a Room. Client Token is necessary to join a Telnyx Room. Client Token will expire after

token_ttl_secs

POST /rooms/{room_id}/actions/refresh_client_token

— Required:

refresh_token

Optional:

token_ttl_secs

(integer)

ruby

response = client.rooms.actions.refresh_client_token(
  "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
  refresh_token: "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0ZWxueXhfdGVsZXBob255IiwiZXhwIjoxNTkwMDEwMTQzLCJpYXQiOjE1ODc1OTA5NDMsImlzcyI6InRlbG55eF90ZWxlcGhvbnkiLCJqdGkiOiJiOGM3NDgzNy1kODllLTRhNjUtOWNmMi0zNGM3YTZmYTYwYzgiLCJuYmYiOjE1ODc1OTA5NDIsInN1YiI6IjVjN2FjN2QwLWRiNjUtNGYxMS05OGUxLWVlYzBkMWQ1YzZhZSIsInRlbF90b2tlbiI6InJqX1pra1pVT1pNeFpPZk9tTHBFVUIzc2lVN3U2UmpaRmVNOXMtZ2JfeENSNTZXRktGQUppTXlGMlQ2Q0JSbWxoX1N5MGlfbGZ5VDlBSThzRWlmOE1USUlzenl6U2xfYURuRzQ4YU81MHlhSEd1UlNZYlViU1ltOVdJaVEwZz09IiwidHlwIjoiYWNjZXNzIn0.gNEwzTow5MLLPLQENytca7pUN79PmPj6FyqZWW06ZeEmesxYpwKh0xRtA0TzLh6CDYIRHrI8seofOO0YFGDhpQ"
)

puts(response)

Returns:

token

(string),

token_expires_at

(date-time)

View a list of room sessions.

GET /rooms/{room_id}/sessions

ruby

page = client.rooms.sessions.list_1("0ccc7b54-4df3-4bca-a65a-3da1ecc777f0")

puts(page)

Returns:

active

(boolean),

created_at

(date-time),

ended_at

(date-time),

id

(uuid),

participants

(array[object]),

record_type

(string),

room_id

(uuid),

updated_at

(date-time)

telnyx-video-ruby

NPX Install

Tags

SKILL.md Content

Telnyx Video - Ruby

Installation

Setup

Error Handling

View a list of room compositions.

Create a room composition.

View a room composition.

Delete a room composition.

View a list of room participants.

View a room participant.

View a list of room recordings.

Delete several room recordings in a bulk.

View a room recording.

Delete a room recording.

View a list of room sessions.

View a room session.

End a room session.

Kick participants from a room session.

Mute participants in room session.

Unmute participants in room session.

View a list of room participants.

View a list of rooms.

Create a room.

View a room.

Update a room.

Delete a room.

Create Client Token to join a room.

Refresh Client Token to join a room.

View a list of room sessions.