Ruby SDK requests, types, and pagination

Pagination

List methods in the Telnyx API are paginated. This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

page = telnyx.access_ip_address.list(page_number: 1, page_size: 50)

# Fetch single item from page.
access_ip_address = page.data[0]
puts(access_ip_address.id)

# Automatically fetches more pages as needed.
page.auto_paging_each do |access_ip_address|
  puts(access_ip_address.id)
end

Alternatively, you can use the #next_page? and #next_page methods for more granular control working with pages.

if page.next_page?
  new_page = page.next_page
  puts(new_page.data[0].id)
end

File uploads

Request parameters that correspond to file uploads can be passed as raw contents, a Pathname instance, StringIO, or more.

require "pathname"

# Use `Pathname` to send the filename and/or avoid paging a large file into memory:
response = telnyx.ai.audio.transcribe(file: Pathname("/path/to/file"))

# Alternatively, pass file contents or a `StringIO` directly:
response = telnyx.ai.audio.transcribe(file: File.read("/path/to/file"))

# Or, to control the filename and/or content type:
file = Telnyx::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "…")
response = telnyx.ai.audio.transcribe(file: file)

puts(response.text)

Note that you can also pass a raw IO descriptor, but this disables retries, as the library can’t be sure if the descriptor is a file or pipe (which cannot be rewound).

BaseModel

All parameter and response objects inherit from Telnyx::Internal::Type::BaseModel, which provides several conveniences, including:

All fields, including unknown ones, are accessible with obj[:prop] syntax, and can be destructured with obj => {prop: prop} or pattern-matching syntax.
Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
Both instances and the classes themselves can be pretty-printed.
Helpers such as #to_h, #deep_to_h, #to_json, and #to_yaml.

Sorbet

This library provides comprehensive RBI definitions, and has no dependency on sorbet-runtime. You can provide typesafe request parameters like so:

telnyx.calls.dial(
  connection_id: "conn12345",
  from: "+15557654321",
  to: "+15551234567",
  webhook_url: "https://your-webhook.url/events"
)

Or, equivalently:

# Hashes work, but are not typesafe:
telnyx.calls.dial(
  connection_id: "conn12345",
  from: "+15557654321",
  to: "+15551234567",
  webhook_url: "https://your-webhook.url/events"
)

# You can also splat a full Params class:
params = Telnyx::CallDialParams.new(
  connection_id: "conn12345",
  from: "+15557654321",
  to: "+15551234567",
  webhook_url: "https://your-webhook.url/events"
)
telnyx.calls.dial(**params)

Enums

Since this library does not depend on sorbet-runtime, it cannot provide T::Enum instances. Instead, we provide “tagged symbols” instead, which is always a primitive at runtime:

# :ALL
puts(Telnyx::Legacy::Reporting::UsageReports::NumberLookupCreateParams::AggregationType::ALL)

# Revealed type: `T.all(Telnyx::Legacy::Reporting::UsageReports::NumberLookupCreateParams::AggregationType, Symbol)`
T.reveal_type(Telnyx::Legacy::Reporting::UsageReports::NumberLookupCreateParams::AggregationType::ALL)

Enum parameters have a “relaxed” type, so you can either pass in enum constants or their literal value:

# Using the enum constants preserves the tagged type information:
telnyx.legacy.reporting.usage_reports.number_lookup.create(
  aggregation_type: Telnyx::Legacy::Reporting::UsageReports::NumberLookupCreateParams::AggregationType::ALL,
  # …
)

# Literal values are also permissible:
telnyx.legacy.reporting.usage_reports.number_lookup.create(
  aggregation_type: :ALL,
  # …
)

Account setup

APIs fundamentals

Server-side SDKs

Telnyx CLI

Development Tools

Migration Guides

Glossary

For AI Agents

Ruby SDK requests, types, and pagination

File uploads

BaseModel

Sorbet

Enums

​Pagination

​File uploads

​BaseModel

​Sorbet

​Enums

Pagination

File uploads

BaseModel

Sorbet

Enums