> ## 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 usage

> Initialize the Telnyx Ruby client and make your first API request.

## Usage

```ruby theme={null}
require "bundler/setup"
require "telnyx"

telnyx = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"] # This is the default and can be omitted
)

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

puts(response.data)
```

### 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).

### Handling errors

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Telnyx::Errors::APIError` will be thrown:

```ruby theme={null}
begin
  number_order = telnyx.number_orders.create(phone_numbers: [{phone_number: "+15558675309"}])
rescue Telnyx::Errors::APIConnectionError => e
  puts("The server could not be reached")
  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
rescue Telnyx::Errors::RateLimitError => e
  puts("A 429 status code was received; we should back off a bit.")
rescue Telnyx::Errors::APIStatusError => e
  puts("Another non-200-range status code was received")
  puts(e.status)
end
```

Error codes are as follows:

| Cause            | Error Type                 |
| ---------------- | -------------------------- |
| HTTP 400         | `BadRequestError`          |
| HTTP 401         | `AuthenticationError`      |
| HTTP 403         | `PermissionDeniedError`    |
| HTTP 404         | `NotFoundError`            |
| HTTP 409         | `ConflictError`            |
| HTTP 422         | `UnprocessableEntityError` |
| HTTP 429         | `RateLimitError`           |
| HTTP >= 500      | `InternalServerError`      |
| Other HTTP error | `APIStatusError`           |
| Timeout          | `APITimeoutError`          |
| Network error    | `APIConnectionError`       |

### Retries

Certain errors will be automatically retried 2 times by default, with a short exponential backoff.

Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.

You can use the `max_retries` option to configure or disable this:

```ruby theme={null}
# Configure the default for all requests:
telnyx = Telnyx::Client.new(
  max_retries: 0 # default is 2
)

# Or, configure per-request:
telnyx.number_orders.create(
  phone_numbers: [{phone_number: "+15558675309"}],
  request_options: {max_retries: 5}
)
```

### Timeouts

By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:

```ruby theme={null}
# Configure the default for all requests:
telnyx = Telnyx::Client.new(
  timeout: nil # default is 60
)

# Or, configure per-request:
telnyx.number_orders.create(
  phone_numbers: [{phone_number: "+15558675309"}],
  request_options: {timeout: 5}
)
```

On timeout, `Telnyx::Errors::APITimeoutError` is raised.

Note that requests that time out are retried by default.