telnyx-toolkit

# Telnyx Toolkit The complete toolkit for building with Telnyx. Includes **ready-to-use tools** and **SDK documentation** for all Telnyx APIs. ## Quick Start ```bash export TELNYX_API_KEY="your_key_here" ``` --- ## 🚀 Getting Started Two companion skills handle account lifecycle. They are included with the toolkit and can also be installed independently via ClawHub. | Skill | Purpose | Path | Install standalone | |-------|---------|------|--------------------| | **Telnyx Bot Signup** | Create a new account or sign into an existing one (PoW challenge → email → API key) | `{baseDir}/getting-started/telnyx-bot-signup/` | `clawhub install telnyx-bot-signup` | | **Telnyx Freemium Upgrade** | Upgrade freemium → professional via GitHub or LinkedIn identity verification | `{baseDir}/getting-started/telnyx-freemium-upgrade/` | `clawhub install telnyx-freemium-upgrade` | ### When to Use Account Signup Hand off to **telnyx-bot-signup** when ANY of these are true: - No API key exists (`TELNYX_API_KEY` not set, `~/.config/telnyx/config.json` missing) - API key is invalid/expired (401 errors from Telnyx API) - User wants to create a new Telnyx account - API key needs to be refreshed after an upgrade (same email, new key) > **Note:** The `bot_signup` endpoint handles both new and existing accounts transparently — just provide the user's email. ### When to Use Account Upgrade Hand off to **telnyx-freemium-upgrade** when ANY of these are true: | Trigger | Detection | |---------|-----------| | Error `10039` | SMS send fails: "destination not verified" | | Error `D60` | Voice call fails: "destination not verified" | | Error `10038` | Feature blocked: "not available on current plan" | | Number limit hit | Second phone number purchase fails | | Cannot add funds | Freemium account cannot add payment method or top up | | Explicit request | User says "upgrade my account" | Before handing off, check `~/.telnyx/upgrade.json` — if `decision` is `APPROVED`, the account is already upgraded (retry the operation instead). If `PASS_TO_HUMAN`, it's under review (don't retry). See the telnyx-freemium-upgrade SKILL.md for full decision tree. Each skill has its own `SKILL.md` with complete instructions. Read the skill's SKILL.md before executing its workflow. --- ## 💳 Balance & Payments Use these endpoints to check balance and add funds programmatically. > **Important:** Top-ups charge the payment method (credit card, PayPal, or ACH) saved in the [Telnyx Portal](https://portal.telnyx.com). There is no API to add a payment method — this is done by the user in the portal. Do not prompt the user about this upfront — just attempt the top-up when needed. If it returns 403, that's when you inform the user they need to add a payment method in the portal. ### Check Balance ```bash curl -s https://api.telnyx.com/v2/balance -H "Authorization: Bearer $TELNYX_API_KEY" ``` **Response:** ```json { "data": { "balance": "300.00", "credit_limit": "100.00", "available_credit": "400.00", "currency": "USD" } } ``` ### Check Auto-Recharge Status Check whether auto-recharge is enabled. If it is, the account will top up automatically when balance drops below the threshold — the agent can just wait and retry instead of manually topping up. ```bash curl -s https://api.telnyx.com/v2/payment/auto_recharge_prefs -H "Authorization: Bearer $TELNYX_API_KEY" ``` **Response:** ```json { "data": { "enabled": true, "threshold_amount": "100.00", "recharge_amount": "100.00", "preference": "credit_paypal" } } ``` If `enabled` is `true` and the agent hits `20100`, wait briefly and retry — auto-recharge should handle it. If `enabled` is `false`, proceed with the top-up endpoint below. > **Note:** Enabling or configuring auto-recharge is a human decision — use the [Telnyx Portal](https://portal.telnyx.com) to change these settings. ### Add Funds (Top Up) Charges the stored payment method on file. Requires a payment method already configured in the Telnyx Portal. ```bash 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"}' ``` The `amount` field is in dollars and cents (e.g., `"100.00"`, `"25.50"`). **Response:** ```json { "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 } } ``` **Error handling:** | Status | Meaning | Action | |--------|---------|--------| | 200 | Transaction submitted | Wait for settlement, then retry the original operation | | 401 | Unauthorized | API key is invalid — hand off to telnyx-bot-signup | | 403 | Forbidden | No stored payment method on file — direct user to [Telnyx Portal](https://portal.telnyx.com) to add one | | 422 | Invalid amount | Amount must be a string with dollars and cents (e.g., `"120.00"`) | ### Payment Error Decision Tree When a Telnyx API call fails with a payment-related error, follow this tree. The agent does not need to know the account tier upfront — the error codes and response codes reveal the right path. **Step 1: Identify the error** | Error Code | Meaning | Go to | |-----------|---------|-------| | `10038` / `10039` | Feature not permitted / limited | Step 2 (upgrade) | | `20100` / `20012` | Insufficient Funds / Account inactive | Step 3 (try top-up) | > **Note:** The API may return `20100` (Insufficient Funds) even on freemium accounts where `10038`/`10039` would be more accurate. Don't assume `20100` means the account is professional — always attempt the top-up and let the response tell you. **Step 2: Feature restriction → Upgrade first** Errors `10038`/`10039` mean the account is freemium. Freemium accounts cannot add payment methods or top up — they must upgrade first. 1. Hand off to **telnyx-freemium-upgrade** → upgrade to professional 2. User adds payment method at [Telnyx Portal](https://portal.telnyx.com) 3. Then proceed to Step 3 if funds are needed **Step 3: Insufficient funds → Try to top up** Always attempt the top-up regardless of account tier — the response will reveal the right path. 1. `GET /v2/balance` — check current available credit 2. `GET /v2/payment/auto_recharge_prefs` — if `enabled: true`, wait briefly and retry (auto-recharge will handle it). If it does, stop here 3. If auto-recharge is off: `POST /v2/payment/stored_payment_transactions` — top up via API 4. **If top-up returns 200** → retry the original operation 5. **If top-up returns 403** → no payment method on file. This is the real signal: - Check `~/.telnyx/upgrade.json` — if `decision` is `APPROVED`, the account is professional but has no payment method → direct user to [Telnyx Portal](https://portal.telnyx.com) to add one - Otherwise, the account is likely freemium → hand off to **telnyx-freemium-upgrade** (Step 2) --- ## 🔧 Tools (Ready-to-Use) These are standalone utilities with scripts you can run directly: | Tool | Description | Path | |------|-------------|------| | **Missions** | AI agent task tracking, voice/SMS assistants, scheduled calls | `{baseDir}/tools/missions/` | | **STT** | Speech-to-text transcription (Whisper) | `{baseDir}/tools/stt/` | | **TTS** | Text-to-speech synthesis | `{baseDir}/tools/tts/` | | **CLI** | Telnyx CLI wrapper and helpers | `{baseDir}/tools/cli/` | | **Network** | WireGuard mesh networking, public IP exposure | `{baseDir}/tools/network/` | | **RAG** | Semantic search with Telnyx Storage + embeddings | `{baseDir}/tools/rag/` | | **10DLC Registration** | Interactive wizard for A2P messaging registration | `{baseDir}/tools/10dlc-registration/` | | **Storage Backup** | Backup/restore workspace to Telnyx Storage | `{baseDir}/tools/storage-backup/` | | **Voice SIP** | SIP-based voice call control | `{baseDir}/tools/voice-sip/` | | **Embeddings** | Semantic search & text embeddings (Telnyx-native) | `{baseDir}/tools/embeddings/` | ### Tool Usage Examples ```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 ``` Each tool has its own `SKILL.md` with detailed usage instructions. --- ## 📚 API Documentation (SDK Reference) SDK documentation for all Telnyx APIs, organized by language: | Language | Path | Skills | |----------|------|--------| | **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 Categories Each language includes documentation for: - **Voice** — Calls, call control, conferencing, streaming, gather - **Messaging** — SMS, MMS, profiles, hosted messaging - **Numbers** — Search, purchase, configure, compliance - **AI** — Inference, assistants, embeddings - **Storage** — Object storage (S3-compatible) - **SIP** — Trunking, connections, integrations - **Video** — Video rooms and conferencing - **Fax** — Programmable fax - **IoT** — SIM management, wireless - **Verify** — Phone verification, 2FA - **Account** — Management, billing, reports - **Porting** — Port numbers in/out - **10DLC** — A2P messaging registration - **TeXML** — TeXML applications - **Networking** — Private networks, SETI - **WebRTC** — Server-side WebRTC ### Finding API Docs ``` {baseDir}/api/{language}/telnyx-{capability}-{language}/SKILL.md ``` Example: `{baseDir}/api/python/telnyx-voice-python/SKILL.md` --- ## 📱 WebRTC Client SDKs Guides for building real-time voice apps on mobile and web: | Platform | Path | |----------|------| | **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/` | --- ## Structure ``` 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/ ```