用途:该技能提供使用 cURL 调用 Telnyx Programmable Fax REST API 的示例,用于以编程方式发送和接收传真、管理传真应用与媒体,并处理 Webhook 事件。
主要能力:
- 传真应用管理:GET /fax_applications 列出应用(支持 sort 等筛选),POST /fax_applications 创建(必填 application_name、webhook_event_url),GET /fax_applications/{id} 获取详情,PATCH 更新,DELETE 删除(若被电话号码占用可能无法删除)。
- 传真操作:GET /faxes 列出传真,POST /faxes 发送传真(必填 connection_id、from、to;可选 quality、media_url、monochrome、store_media、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。
必要用法:curl 已预装于 macOS、Linux 和 Windows 10+。设置环境变量 export TELNYX_API_KEY="YOUR_API_KEY_HERE",所有请求使用 Authorization: Bearer $TELNYX_API_KEY。电话号码须为 E.164 格式(如 +13125550001),含加号和国家代码,不含空格、连字符或括号。列表接口分页使用 page[number] 和 page[size],检查响应中的 meta.total_pages。
限制与注意:所有 API 调用可能因网络错误、限流(429)、校验错误(422)或认证错误(401)失败,生产代码须处理错误。常见错误码:401 无效 API 密钥,403 权限不足,404 资源未找到,422 校验错误,429 限流(建议指数退避重试)。发送传真时文件超过 50MB 或超过 350 页会分别以 file_size_limit_exceeded 和 page_count_limit_exceeded 失败。Webhook 使用 Ed25519 签名(非 HMAC/Standard Webhooks),请求含 telnyx-signature-ed25519 和 telnyx-timestamp 头,时间戳超过 5 分钟应拒绝以防重放;端点须在 2 秒内返回 2xx,否则 Telnyx 最多重试 3 次;可在 Telnyx Portal 配置故障转移 URL。Webhook 事件包括 fax.delivered、fax.failed、fax.media.processed、fax.queued、fax.sending.started。
暂未提供:价格、免费额度、平台可用性等具体收费或平台信息。