Telnyx Fax - Ruby 是 Telnyx 可编程传真 API 的 Ruby SDK 使用示例，面向需要在 Ruby 应用中集成传真收发能力的开发者。
用途 通过 Telnyx 的 Programmable Fax API，以编程方式发送和接收传真，并管理传真应用（Fax Applications）与传真媒体。
安装与初始化 安装命令：gem install telnyx 初始化示例： require "telnyx" client = Telnyx::Client.new( api_key: ENV["TELNYX_API_KEY"], ) 后续所有示例均假设 client 已按上述方式初始化。
错误处理 所有 API 调用都可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。生产代码中应始终处理错误，示例使用 Telnyx::Errors::APIConnectionError、Telnyx::Errors::RateLimitError、Telnyx::Errors::APIStatusError 进行捕获。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 速率限制（使用指数退避重试）。
重要说明 电话号码必须为 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能有空格、短横线或括号。分页可使用 .auto_paging_each 自动迭代：page.auto_paging_each { |item| puts item.id }。
传真应用管理
- 列出所有传真应用：GET /fax_applications，使用 client.fax_applications.list。返回字段包括 active、anchorsite_override、application_name、created_at、id、inbound、outbound、record_type、tags、updated_at、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs。
- 创建传真应用：POST /fax_applications，必填 application_name、webhook_event_url；可选 active、anchorsite_override、inbound、outbound、tags、webhook_event_failover_url、webhook_timeout_secs。创建后可通过 /phone_numbers 端点将电话号码分配给应用。
- 检索传真应用：GET /fax_applications/{id}。
- 更新传真应用：PATCH /fax_applications/{id}，必填 application_name、webhook_event_url；可选 active、anchorsite_override、fax_email_recipient、inbound、outbound、tags、webhook_event_failover_url、webhook_timeout_secs。
- 删除传真应用：DELETE /fax_applications/{id}。若应用正被电话号码使用，删除可能被阻止。
传真操作
- 查看传真列表：GET /faxes，使用 client.faxes.list。返回字段包括 client_state、connection_id、created_at、direction、from、from_display_name、id、media_name、media_url、preview_url、quality、record_type、status、store_media、stored_media_url、to、updated_at、webhook_failover_url、webhook_url。
- 发送传真：POST /faxes，必填 connection_id、from、to；可选 black_threshold、client_state、from_display_name、media_name、media_url、monochrome、preview_format、quality、store_media、store_preview、t38_enabled、webhook_url。文件有大小和页数限制：超过 50MB 会失败并返回 file_size_limit_exceeded，超过 350 页会失败并返回 page_count_limit_exceeded。
- 查看传真：GET /faxes/{id}。
- 删除传真：DELETE /faxes/{id}。
- 取消传真：POST /faxes/{id}/actions/cancel，可取消处于 queued、media.processed、originated 或 sending 状态的出站传真。
- 刷新传真：POST /faxes/{id}/actions/refresh，用于在入站传真的 media_url 过期后刷新。
Webhook Telnyx 使用 Ed25519 对 Webhook 签名，每个请求包含 telnyx-signature-ed25519 和 telnyx-timestamp 头。生产环境应始终验证签名，可使用 client.webhooks.unwrap(payload, headers) 进行验证。 支持的 Webhook 事件：fax.delivered（传真已送达）、fax.failed（传真失败）、fax.media.processed（传真媒体已处理）、fax.queued（传真已排队）、fax.sending.started（传真开始发送）。 所有 Webhook 均包含 telnyx-timestamp 和 telnyx-signature-ed25519 头用于 Ed25519 签名验证。
适用场景 适用于需要在 Ruby 应用中自动化传真收发、管理传真应用配置、处理传真状态回调的业务场景。
限制 资料未提供收费、价格、平台支持范围等额外信息。