> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby SDK requests, types, and pagination

> Models, Sorbet types, file uploads, 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:

```ruby theme={null}
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.

```ruby theme={null}
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`](https://rubyapi.org/3.2/o/pathname) instance, [`StringIO`](https://rubyapi.org/3.2/o/stringio), or more.

```ruby theme={null}
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:

1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.

2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.

3. Both instances and the classes themselves can be pretty-printed.

4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.

## Sorbet

This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.

You can provide typesafe request parameters like so:

```ruby theme={null}
telnyx.calls.dial(
  connection_id: "conn12345",
  from: "+15557654321",
  to: "+15551234567",
  webhook_url: "https://your-webhook.url/events"
)
```

Or, equivalently:

```ruby theme={null}
# 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`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:

```ruby theme={null}
# :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:

```ruby theme={null}
# 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,
  # …
)
```