用途
telnyx-fax-go 是面向 Go 开发者的 Telnyx Fax 编程示例技能，目的是让开发者通过 Telnyx Go SDK 以代码方式发送和接收传真，并管理传真应用与传真媒体。
主要能力
传真应用管理
- 列出所有传真应用（GET /fax_applications），返回数据位于响应的 data 属性中，可通过过滤器调整列表内容。
- 创建传真应用（POST /fax_applications），application_name 与 webhook_event_url 为必填项，创建后可通过 /phone_numbers 端点将电话号码分配给应用。
- 获取单个传真应用（GET /fax_applications/{id}）。
- 更新传真应用（PATCH /fax_applications/{id}），application_name 与 webhook_event_url 为必填项。
- 删除传真应用（DELETE /fax_applications/{id}），若应用仍被电话号码使用，删除可能被阻止。
传真操作
- 查看传真列表（GET /faxes）。
- 发送传真（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。
- 查看单个传真（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 请求头。示例展示了在 Webhook 处理函数中调用 client.Webhooks.Unwrap 验证签名并解析事件负载。文档列出的事件包括：fax.delivered（传真已送达）、fax.failed（传真失败）、fax.media.processed（传真媒体已处理）、fax.queued（传真已排队）、fax.sending.started（传真开始发送），并给出了对应负载字段说明。
使用方式
安装
go get github.com/team-telnyx/telnyx-go
初始化
import ( "context" "fmt" "os"
"github.com/team-telnyx/telnyx-go" "github.com/team-telnyx/telnyx-go/option" )
client := telnyx.NewClient( option.WithAPIKey(os.Getenv("TELNYX_API_KEY")), )
上述所有示例均假定 client 已按此方式初始化。
注意事项
- 电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀与国家代码，不得包含空格、连字符或括号。
- 分页可使用 ListAutoPaging() 自动遍历：iter := client.Resource.ListAutoPaging(ctx, params); for iter.Next() { item := iter.Current() }。
- 生产代码需处理错误：网络错误、速率限制（429）、校验错误（422）、鉴权错误（401）。常见错误码：401 无效 API Key，403 权限不足，404 资源不存在，422 校验错误（检查字段格式），429 速率限制（使用指数退避重试）。
适用场景
需要通过 Go 程序自动化传真收发流程、管理传真应用配置、或对接 Telnyx 可编程传真 API 的开发者场景。
限制
传真文件存在大小与页数限制：文件大于 50MB 会失败并返回 file_size_limit_exceeded，页数超过 350 页会失败并返回 page_count_limit_exceeded。取消操作仅适用于 queued、media.processed、originated、sending 这几种状态的外呼传真。传真应用的删除在应用被电话号码占用时可能被阻止。关于收费、价格、具体可用平台等信息，资料中暂未提供。