介绍
# Telnyx Toolkit
用于构建 Telnyx 应用的完整工具包。包含所有 Telnyx API 的**现成工具**和**SDK 文档**。
## 快速开始
```bash export TELNYX_API_KEY="your_key_here" ```
---
## 🚀 入门指南
两个配套技能负责处理账户生命周期。它们包含在工具包中，也可以通过 ClawHub 单独安装。
| 技能 | 用途 | 路径 | 独立安装 | |-------|---------|------|--------------------| | **Telnyx Bot 注册** | 创建新账户或登录现有账户（PoW 验证 → 邮箱 → API 密钥） | `{baseDir}/getting-started/telnyx-bot-signup/` | `clawhub install telnyx-bot-signup` | | **Telnyx 免费版升级** | 通过 GitHub 或 LinkedIn 身份验证将免费版升级为专业版 | `{baseDir}/getting-started/telnyx-freemium-upgrade/` | `clawhub install telnyx-freemium-upgrade` |
### 何时使用账户注册
当以下任一情况为真时，转交给 **telnyx-bot-signup**：
- 不存在 API 密钥（未设置 `TELNYX_API_KEY`，缺少 `~/.config/telnyx/config.json`） - API 密钥无效/过期（来自 Telnyx API 的 401 错误） - 用户希望创建新的 Telnyx 账户 - 升级后需要刷新 API 密钥（相同邮箱，新密钥）
> **注意：** `bot_signup` 端点透明处理新账户和现有账户 —— 只需提供用户的电子邮件。
### 何时使用账户升级
当以下任一情况为真时，转交给 **telnyx-freemium-upgrade**：
| 触发条件 | 检测方式 | |---------|-----------| | 错误 `10039` | 短信发送失败：“目标未验证” | | 错误 `D60` | 语音通话失败：“目标未验证” | | 错误 `10038` | 功能被阻止：“当前计划不可用” | | 达到号码限制 | 第二个电话号码购买失败 | | 无法添加资金 | 余额充值或付款方式被拒绝 | | 明确请求 | 用户说“升级我的账户” |
在转交之前，请检查 `~/.telnyx/upgrade.json` —— 如果 `decision` 为 `APPROVED`，则账户已升级（改为重试该操作）。如果是 `PASS_TO_HUMAN`，则正在审核中（不要重试）。有关完整的决策树，请参阅 telnyx-freemium-upgrade 的 SKILL.md。
每个技能都有自己的 `SKILL.md`，包含完整的说明。在执行其工作流程之前，请阅读该技能的 SKILL.md。
---
## 🔧 工具（现成可用）
这些是独立的实用工具，包含可以直接运行的脚本：
| 工具 | 描述 | 路径 | |------|-------------|------| | **Missions** | AI 智能体任务跟踪、语音/短信助手、预定呼叫 | `{baseDir}/tools/missions/` | | **STT** | 语音转文字转录（Whisper） | `{baseDir}/tools/stt/` | | **TTS** | 文字转语音合成 | `{baseDir}/tools/tts/` | | **CLI** | Telnyx CLI 封装和辅助工具 | `{baseDir}/tools/cli/` | | **Network** | WireGuard 网状网络、公共 IP 暴露 | `{baseDir}/tools/network/` | | **RAG** | 基于 Telnyx Storage + 嵌入的语义搜索 | `{baseDir}/tools/rag/` | | **10DLC 注册** | A2P 消息注册的交互式向导 | `{baseDir}/tools/10dlc-registration/` | | **Storage 备份** | 将工作区备份/恢复到 Telnyx Storage | `{baseDir}/tools/storage-backup/` | | **Voice SIP** | 基于 SIP 的语音通话控制 | `{baseDir}/tools/voice-sip/` | | **Embeddings** | 语义搜索和文本嵌入（Telnyx 原生） | `{baseDir}/tools/embeddings/` |
### 工具使用示例
```bash # 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 文档，按语言组织：
| 语言 | 路径 | 技能数 | |----------|------|--------| | **JavaScript** | `{baseDir}/api/javascript/` | 35 | | **Python** | `{baseDir}/api/python/` | 35 | | **Go** | `{baseDir}/api/go/` | 35 | | **Java** | `{baseDir}/api/java/` | 35 | | **Ruby** | `{baseDir}/api/ruby/` | 35 |
### API 类别
每种语言都包含以下文档：
- **Voice** — 通话、通话控制、会议、流传输、收集 - **Messaging** — 短信、彩信、资料、托管消息 - **Numbers** — 搜索、购买、配置、合规 - **AI** — 推理、助手、嵌入 - **Storage** — 对象存储（兼容 S3） - **SIP** — 中继、连接、集成 - **Video** — 视频房间和会议 - **Fax** — 可编程传真 - **IoT** — SIM 管理、无线 - **Verify** — 电话验证、双因素认证 - **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 上构建实时语音应用的指南：
| 平台 | 路径 | |----------|------| | **iOS** | `{baseDir}/webrtc-clients/ios/` | | **Android** | `{baseDir}/webrtc-clients/android/` | | **Flutter** | `{baseDir}/webrtc-clients/flutter/` | | **JavaScript (Web)** | `{baseDir}/webrtc-clients/javascript/` | | **React Native** | `{baseDir}/webrtc-clients/react-native/` |
---
## 结构
``` 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 文档](https://developers.telnyx.com) - [Telnyx 门户](https://portal.telnyx.com) - [API 参考](https://developers.telnyx.com/api/v2/overview)