Telnyx 工具包

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

快速开始

export TELNYX_API_KEY="your_key_here"

🚀 入门指南

两个配套技能负责处理账户生命周期。它们包含在工具包中，也可以通过 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— 如果决定是已批准，则账户已升级（应重试操作）。如果转交人工处理，该申请正在审核中（请勿重试）。完整决策流程请参阅 telnyx-freemium-upgrade 的 SKILL.md 文件。

每个技能都有其独立的SKILL.md 文件，其中包含完整说明。执行技能工作流前请务必阅读其 SKILL.md 文件。

💳 余额与支付

使用以下端点可编程查询余额及充值。

重要提示：充值操作将向Telnyx 门户网站中保存的支付方式（信用卡、PayPal 或 ACH）发起扣款。没有添加支付方式的 API 接口——这需要用户在门户网站中自行操作。请勿提前向用户提示此信息，仅在需要时尝试充值。若返回 403 错误，此时再告知用户需在门户网站中添加支付方式。

查询余额

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"
  }
}

检查自动充值状态

检查是否启用自动充值功能。若已启用，当余额低于阈值时账户将自动充值——此时代理只需等待并重试，无需手动充值。

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"
  }
}

若已启用为真且代理遇到20100时，请稍作等待后重试——自动充值功能应会处理此情况。若已启用为假，则请继续使用下方的充值端点进行操作。

注意：启用或配置自动充值需由人工决定——请通过Telnyx门户更改这些设置。

添加资金（充值）

向已存档的支付方式扣款。需要在Telnyx门户中预先配置支付方式。

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"}'

其中金额字段以美元和美分表示（例如："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调用因支付相关错误而失败时，请遵循此决策树。代理无需预先知道账户等级 — 错误代码和响应代码会揭示正确的处理路径。

第一步：识别错误

注意：API 可能返回20100（资金不足）错误，即使在免费增值账户上，而10038/10039本应更为准确。不要假定20100错误意味着账户是专业版——请始终尝试充值操作，并让响应结果来告诉你真实情况。

步骤2：功能限制 → 先升级

错误10038/10039表示账户是免费增值账户。免费增值账户无法添加支付方式或充值——必须先升级。

1. 转交至telnyx-freemium-upgrade→ 升级为专业版
2. 用户在Telnyx 门户网站
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，账户为专业版但无支付方式 → 引导用户至Telnyx门户添加支付方式
   • 否则，账户可能为免费增值版 → 转交至telnyx-freemium-upgrade（步骤2）

🔧 工具（即用型）

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

工具使用示例

# Create a mission and schedule calls
python3 {baseDir}/tools/missions/scripts/telnyx_api.py init "Find contractors" "Call contractors and get quotes" "User request" '[{"step_id": "calls", "description": "Make calls", "sequence": 1}]'

# Transcribe audio
python3 {baseDir}/tools/stt/scripts/telnyx-stt.py /path/to/audio.mp3

# Generate speech  
python3 {baseDir}/tools/tts/scripts/telnyx-tts.py "Hello world" -o output.mp3

# Join mesh network
{baseDir}/tools/network/join.sh

# Index files for RAG
python3 {baseDir}/tools/rag/sync.py

# 10DLC registration wizard
{baseDir}/tools/10dlc-registration/setup.sh

# Semantic search
python3 {baseDir}/tools/embeddings/search.py "your query" --bucket your-bucket

# Index a file for search
python3 {baseDir}/tools/embeddings/index.py upload /path/to/file.md

每个工具都有其对应的SKILL.md文件，其中包含详细的使用说明。

📚 API文档（SDK参考）

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

API 分类

每种语言都包含以下内容的文档：

• 语音— 通话、通话控制、会议、流媒体、信息收集
• 消息— 短信、彩信、配置文件、托管消息
• 号码— 搜索、购买、配置、合规
• 人工智能— 推理、助手、嵌入
• 存储— 对象存储（S3兼容）
• SIP— 中继、连接、集成
• 视频— 视频会议室与视频会议
• 传真— 可编程传真
• 物联网— SIM卡管理，无线通信
• 验证服务— 电话验证，双因素认证
• 账户— 管理，计费，报告
• 号码移植— 号码转入/转出
• 10DLC（十位长代码）— A2P消息注册
• TeXML— TeXML应用程序
• 网络— 私有网络，SETI
• WebRTC— 服务器端WebRTC

查找API文档

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

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

📱 WebRTC客户端SDK

在移动端和网页端构建实时语音应用的指南：

结构

telnyx-toolkit/
├── SKILL.md              # This file (index)
├── getting-started/      # Account creation & upgrade
│   ├── telnyx-bot-signup/
│   └── telnyx-freemium-upgrade/
├── tools/                # Ready-to-use utilities
│   ├── missions/         # AI agent task tracking
│   ├── stt/
│   ├── tts/
│   ├── cli/
│   ├── network/
│   ├── rag/
│   ├── 10dlc-registration/
│   ├── storage-backup/
│   ├── voice-sip/
│   └── embeddings/
├── api/                  # SDK documentation
│   ├── javascript/       # 35 skills
│   ├── python/           # 35 skills
│   ├── go/               # 35 skills
│   ├── java/             # 35 skills
│   └── ruby/             # 35 skills
└── webrtc-clients/       # Mobile/Web SDK guides
    ├── ios/
    ├── android/
    ├── flutter/
    ├── javascript/
    └── react-native/

资源

• Telnyx API 文档
• Telnyx 门户
• API 参考