Telnyx Toolkit

构建 Telnyx 应用的完整工具集。包含所有 Telnyx API 的开箱即用工具与SDK 文档。

快速开始

export TELNYX_API_KEY="your_key_here"

🚀 入门指南

两个配套技能共同管理账户生命周期。它们随 Toolkit 一并提供，也可通过 ClawHub 独立安装。

何时使用账户注册流程

满足以下任一条件时，应交由 telnyx-bot-signup 处理：

• 尚无 API 密钥（TELNYX_API_KEY 未设置，或 ~/.config/telnyx/config.json 缺失）
• API 密钥无效或已过期（Telnyx API 返回 401 错误）
• 用户希望创建新的 Telnyx 账户
• 升级后需刷新 API 密钥（邮箱不变，密钥更新）

注意：bot_signup 接口可透明处理新账户与已有账户——只需向其提供用户的邮箱地址即可。

何时使用账户升级流程

满足以下任一条件时，应交由 telnyx-freemium-upgrade 处理：

移交前，请先检查 ~/.telnyx/upgrade.json 文件：若其中 decision 字段值为 APPROVED，说明账户已完成升级（此时应重试原操作）；若为 PASS_TO_HUMAN，则表示仍在人工审核中（请勿重试）。完整的决策逻辑详见 telnyx-freemium-upgrade 目录下的 SKILL.md。

每个技能均配有独立的 SKILL.md 文件，含完整使用说明。执行任一技能的工作流前，请务必先阅读其对应的 SKILL.md。

💳 余额与支付

使用以下接口可编程化查询余额及充值。

重要提示：充值操作将从 Telnyx Portal 中保存的支付方式（信用卡、PayPal 或 ACH）扣款。Telnyx API 不支持添加支付方式——该操作必须由用户在 Portal 中完成。请勿提前向用户提示此限制；仅在实际需要充值时发起请求。若返回 403 错误，才告知用户需前往 Telnyx Portal 添加支付方式。

查询余额

curl -s https://api.telnyx.com/v2/balance -H "Authorization: Bearer $TELNYX_API_KEY"

响应示例：

{
  "data": {
    "balance": "300.00",
    "credit_limit": "100.00",
    "available_credit": "400.00",
    "currency": "USD"
  }
}

查询自动充值状态

检查是否已启用自动充值。若已启用，当余额低于阈值时账户将自动充值——此时 Agent 可稍作等待后重试，无需手动充值。

curl -s https://api.telnyx.com/v2/payment/auto_recharge_prefs -H "Authorization: Bearer $TELNYX_API_KEY"

响应示例：

{
  "data": {
    "enabled": true,
    "threshold_amount": "100.00",
    "recharge_amount": "100.00",
    "preference": "credit_paypal"
  }
}

若 enabled 为 true 且 Agent 遇到错误码 20100，建议短暂等待后重试——自动充值机制将自动处理。若 enabled 为 false，请继续调用下方的充值接口。

注意：启用或配置自动充值属于人工决策行为——请通过 Telnyx Portal 修改相关设置。

充值（Top Up）

对 Telnyx Portal 中已配置的支付方式进行扣款。要求用户已在 Portal 中完成支付方式配置。

curl -s -X POST https://api.telnyx.com/v2/payment/stored_payment_transactions -H "Authorization: Bearer $TELNYX_API_KEY" -H "Content-Type: application/json" -d '{"amount": "100.00"}'

amount 字段单位为美元与美分（例如："100.00"、"25.50"）。

响应示例：

{
  "data": {
    "id": "de06811a-2e43-4561-af5a-7d0a26e20aaa",
    "record_type": "transaction",
    "amount_cents": 10000,
    "processor_status": "submitted_for_settlement",
    "amount_currency": "USD",
    "created_at": "2026-02-25T10:00:00Z",
    "auto_recharge": false
  }
}

错误处理：

支付错误决策树

当 Telnyx API 调用因支付相关错误失败时，请按此决策树执行。Agent 无需预先知晓账户等级——错误码与响应码本身即指明了正确路径。

步骤 1：识别错误类型

注意：API 可能对 freemium 账户返回 20100（余额不足），而更准确的错误码应为 10038/10039。请勿假设 20100 表示账户已是 professional —— 始终尝试充值，并依据响应结果判断后续动作。

步骤 2：功能受限 → 优先升级

错误码 10038/10039 表明账户处于 freemium 状态。freemium 账户无法添加支付方式或充值，必须先升级。

1. 移交至 telnyx-freemium-upgrade → 升级为 professional 账户
2. 用户在 Telnyx Portal 中添加支付方式
3. 若仍需充值，则进入步骤 3

步骤 3：余额不足 → 尝试充值

无论账户等级如何，始终先尝试充值——响应结果将揭示真实状况。

1. GET /v2/balance — 查询当前可用信用额度
2. GET /v2/payment/auto_recharge_prefs — 若 enabled: true，则短暂等待后重试（自动充值将处理）；若成功则流程终止
3. 若自动充值关闭：调用 POST /v2/payment/stored_payment_transactions 进行 API 充值
4. 若充值返回 200 → 重试原始操作
5. 若充值返回 403 → 账户未配置支付方式。这是关键信号：
   • 检查 ~/.telnyx/upgrade.json — 若 decision 为 APPROVED，说明账户已是 professional 但尚未添加支付方式 → 引导用户前往 Telnyx Portal 添加
   • 否则，账户大概率仍为 freemium → 移交至 telnyx-freemium-upgrade（步骤 2）

🔧 工具（开箱即用）

这些是具备独立脚本的实用工具，可直接运行：

工具使用示例

# 创建 Mission 并安排外呼任务
python3 {baseDir}/tools/missions/scripts/telnyx_api.py init "寻找承包商" "致电承包商并获取报价" "用户请求" '[{"step_id": "calls", "description": "拨打电话", "sequence": 1}]'

# 转录音频文件
python3 {baseDir}/tools/stt/scripts/telnyx-stt.py /path/to/audio.mp3

# 生成语音
python3 {baseDir}/tools/tts/scripts/telnyx-tts.py "Hello world" -o output.mp3

# 加入网状网络
{baseDir}/tools/network/join.sh

# 为 RAG 索引文件
python3 {baseDir}/tools/rag/sync.py

# 启动 10DLC 注册向导
{baseDir}/tools/10dlc-registration/setup.sh

# 执行语义搜索
python3 {baseDir}/tools/embeddings/search.py "your query" --bucket your-bucket

# 为搜索索引单个文件
python3 {baseDir}/tools/embeddings/index.py upload /path/to/file.md

每个工具均配有独立的 SKILL.md 文件，含详细使用说明。

📚 API 文档（SDK 参考）

所有 Telnyx API 的 SDK 文档，按编程语言组织：

API 分类

每种语言的文档均涵盖以下能力：

• Voice — 语音通话、呼叫控制、会议、流媒体、按键收集（gather）
• Messaging — 短信（SMS）、彩信（MMS）、消息配置文件、托管消息服务
• Numbers — 号码搜索、购买、配置、合规性检查
• AI — 推理、助手、嵌入向量（embeddings）
• Storage — 对象存储（兼容 S3）
• SIP — SIP 中继、连接、集成
• Video — 视频会议室与会议
• Fax — 可编程传真
• IoT — SIM 卡管理、无线通信
• Verify — 电话号码验证、双因素认证（2FA）
• Account — 账户管理、账单、报表
• Porting — 号码携入/携出
• 10DLC — A2P 消息注册
• TeXML — TeXML 应用程序
• Networking — 私有网络、SETI
• WebRTC — 服务端 WebRTC 支持

查找 API 文档

{baseDir}/api/{language}/telnyx-{capability}-{language}/SKILL.md

示例：{baseDir}/api/python/telnyx-voice-python/SKILL.md

📱 WebRTC 客户端 SDK

面向移动端与 Web 端实时语音应用的开发指南：

目录结构

telnyx-toolkit/
├── SKILL.md              # 本文件（主索引）
├── getting-started/      # 账户创建与升级
│   ├── telnyx-bot-signup/
│   └── telnyx-freemium-upgrade/
├── tools/                # 开箱即用工具
│   ├── missions/         # AI Agent 任务追踪
│   ├── stt/
│   ├── tts/
│   ├── cli/
│   ├── network/
│   ├── rag/
│   ├── 10dlc-registration/
│   ├── storage-backup/
│   ├── voice-sip/
│   └── embeddings/
├── api/                  # SDK 文档
│   ├── javascript/       # 35 个技能
│   ├── python/           # 35 个技能
│   ├── go/               # 35 个技能
│   ├── java/             # 35 个技能
│   └── ruby/             # 35 个技能
└── webrtc-clients/       # 移动端/Web SDK 指南
    ├── ios/
    ├── android/
    ├── flutter/
    ├── javascript/
    └── react-native/

资源

• Telnyx API 文档
• Telnyx Portal
• API 参考文档