用途
该技能面向需要管理 Telnyx SIP 集成相关资源的开发者，提供一组基于 curl 的 REST API 调用示例。文档覆盖自定义存储凭证、Dialogflow 连接、外部连接（External Connections）及其下属的日志、地址、电话号码、发布（Releases）与上传（Uploads）等资源。
主要能力
自定义存储凭证（Custom Storage Credentials）
- 获取、创建、更新、删除存储凭证配置。
- 使用
GET/POST/PUT/DELETE /custom_storage_credentials/{connection_id}。 - 返回字段包括 backend（gcs、s3、azure）与 configuration。
Dialogflow 连接（Dialogflow Connections）
- 获取、创建、更新、删除与 CallControl 连接关联的 Dialogflow 连接。
- 使用
GET/POST/PUT/DELETE /dialogflow_connections/{connection_id}。 - 返回字段包括 connection_id、conversation_profile_id、environment、record_type、service_account。
外部连接（External Connections）
- 列出、创建、获取、更新、删除 External Connection。
- 创建时
external_sip_connection（枚举 zoom、operator_connect）与 outbound 为必填。 - 支持字段包括 active、inbound、tags、webhook_event_failover_url、webhook_event_url、webhook_timeout_secs。
- 删除可能因号码占用、连接处于活动状态或为 Operator Connect 连接而被阻止；移除 Operator Connect 集成需联系 Telnyx 支持。
日志消息（Log Messages）
- 列出所有外部连接的日志消息、获取单条日志、删除（Dismiss）日志消息。
地址与位置（Civic Addresses / Locations）
- 列出、获取外部连接下的 civic addresses 及位置。
- 更新位置静态紧急地址：
PATCH /external_connections/{id}/locations/{location_id}，必填 static_emergency_address_id。
电话号码（Phone Numbers）
- 列出、获取外部连接下的电话号码，并异步更新号码设置（可选 location_id）。
发布（Releases）与上传（Uploads）
- 列出、获取 Release 请求，Release 在变更 Microsoft Teams 号码的 connection_id 时自动创建。
- 列出、创建 Upload 请求，并刷新所有 Upload 请求状态。创建 Upload 时 number_ids 必填，最多 1000 个号码；civic_address_id 与 location_id 只能提供其一；usage 枚举为 calling_user_assignment、first_party_app_assignment。
使用方式
- curl 在 macOS、Linux 与 Windows 10+ 上预装。
- 设置环境变量：
export TELNYX_API_KEY="YOUR_API_KEY_HERE"。 - 所有示例使用
Authorization: Bearer $TELNYX_API_KEY进行认证。 - 分页：列表端点返回分页结果，可使用
page[number]与page[size]查询参数翻页，并检查响应中的meta.total_pages。
错误处理
所有 API 调用可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。生产代码中应始终处理错误。示例通过 -w "\n%{http_code}" 捕获 HTTP 状态码并使用 case 分支处理：
response=$(curl -s -w "\n%{http_code}" \
-X POST "https://api.telnyx.com/v2/messages" \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+13125550001", "from": "+13125550002", "text": "Hello"}')
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')
case $http_code in
2*) echo "Success: $body" ;;
422) echo "Validation error — check required fields and formats" ;;
429) echo "Rate limited — retry after delay"; sleep 1 ;;
401) echo "Authentication failed — check TELNYX_API_KEY" ;;
*) echo "Error $http_code: $body" ;;
esac
常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 速率限制（使用指数退避重试）。
适用场景
- 通过命令行脚本管理 Telnyx SIP 中继集成配置。
- 为 SIP 中继接入配置外部连接、存储凭证与 Dialogflow 连接。
- 管理 Microsoft Teams 相关号码上传、发布流程与紧急地址。
限制
- 文档未提供各接口的速率限制具体阈值、计费方式与价格信息。
- 创建 Upload 请求时 number_ids 数组最大支持 1000 个号码；civic_address_id 与 location_id 只能提供其一。
- 部分外部连接删除操作可能被阻止，需联系 Telnyx 支持。
- 文档中的返回字段、枚举值与必填/可选要求以原文为准。