| name | telnyx-toolkit |
| description | Complete Telnyx toolkit — ready-to-use tools (STT, TTS, RAG, Networking, 10DLC) plus SDK documentation for JavaScript, Python, Go, Java, and Ruby. |
| metadata | {"openclaw":{"emoji":"📞","requires":{"env":["TELNYX_API_KEY"]},"primaryEnv":"TELNYX_API_KEY"}} |
Telnyx Toolkit
The complete toolkit for building with Telnyx. Includes ready-to-use tools and SDK documentation for all Telnyx APIs.
Quick Start
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. 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
curl -s https://api.telnyx.com/v2/balance -H "Authorization: Bearer $TELNYX_API_KEY"
Response:
{
"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.
curl -s https://api.telnyx.com/v2/payment/auto_recharge_prefs -H "Authorization: Bearer $TELNYX_API_KEY"
Response:
{
"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 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.
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:
{
"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 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.
- Hand off to telnyx-freemium-upgrade → upgrade to professional
- User adds payment method at Telnyx Portal
- 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.
GET /v2/balance — check current available creditGET /v2/payment/auto_recharge_prefs — if enabled: true, wait briefly and retry (auto-recharge will handle it). If it does, stop here- If auto-recharge is off:
POST /v2/payment/stored_payment_transactions — top up via API
- If top-up returns 200 → retry the original operation
- 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 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
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}]'
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
python3 {baseDir}/tools/rag/sync.py
{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
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/
Resources
