telnyx-fax-ruby

用途

Telnyx Fax - Ruby 面向需要在 Ruby 项目中以编程方式收发传真的开发者，基于 Telnyx 可编程传真 API 提供 Ruby SDK 示例，可用于管理传真应用（Fax Applications）、发送与接收传真、访问传真媒体资源，并处理传真状态 webhook 事件。

主要能力

传真应用管理：列出、创建、查询、更新和删除 Fax Applications。创建应用时 application_name 与 webhook_event_url 为必填；可选参数包括 active、anchorsite_override、inbound、outbound、tags、webhook_event_failover_url、webhook_timeout_secs 等。创建后可通过 /phone_numbers 端点将电话号码分配给应用。删除应用时，若该应用正被电话号码使用，删除可能被阻止。
传真操作：列出传真、发送传真、查看传真、删除传真，以及取消处于 queued、media.processed、originated 或 sending 状态的外发传真；还可刷新已过期的入站传真 media_url。
发送传真参数：必填 connection_id、from、to；可选包括 black_threshold、client_state、from_display_name、media_name、media_url、monochrome、preview_format（pdf、tiff）、quality（normal、high、very_high、ultra_light、ultra_dark）、store_media、store_preview、t38_enabled、webhook_url。
Webhook 事件：支持 fax.delivered、fax.failed、fax.media.processed、fax.queued、fax.sending.started 等事件，回调包含 telnyx-timestamp 与 telnyx-signature-ed25519 头用于 Ed25519 签名校验。

使用方式

安装：gem install telnyx。

初始化：

require "telnyx"

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

发送传真示例：

fax = client.faxes.create(connection_id: "234423", from: "+13125790015", to: "+13127367276", media_url: "https://example.com/document.pdf")
puts(fax)

创建传真应用示例：

fax_application = client.fax_applications.create(application_name: "fax-router", webhook_event_url: "https://example.com")
puts(fax_application)

分页：使用 .auto_paging_each 自动迭代，如 page.auto_paging_each { |item| puts item.id }。

Webhook 校验示例（以 Sinatra 为例，需使用原始 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

错误处理

所有 API 调用可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败。生产代码应始终捕获错误，示例：

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

常见错误码：401 无效 API key、403 权限不足、404 资源未找到、422 校验错误（检查字段格式）、429 触发速率限制（使用指数退避重试）。

适用场景

适合需要在 Ruby 应用中集成传真收发能力（如文档传输、表单提交、回执接收等），并通过 webhook 跟踪传真状态变化、管理传真应用配置的场景。

限制

电话号码必须为 E.164 格式（如 +13125550001），包含 + 前缀与国家代码，不含空格、短横线或括号。
发送传真时，文件超过 50MB 会以 file_size_limit_exceeded 失败，超过 350 页会以 page_count_limit_exceeded 失败。
仅可取消处于 queued、media.processed、originated 或 sending 状态的传真。
关于定价、计费、速率限制具体额度、地区可用性等信息，资料暂未提供。

技能介绍

用途

主要能力

使用方式

错误处理

适用场景

限制