Telnyx Toolkit

Complete Telnyx toolkit — ready-to-use tools (STT, TTS, RAG, Networking, 10DLC) plus SDK documentation for JavaScript, Python, Go, Java, and Ruby.

Security Scan

The skill largely matches a Telnyx SDK/toolkit, but included scripts reference additional credentials, perform privileged system/network operations, and instruct automatic payments — some capabilities and side effects are not declared or adequately constrained.

Purpose & Capability

The declared purpose (Telnyx toolkit: STT, TTS, RAG, Networking, 10DLC and SDK docs) matches most files (many auto-generated SDK SKILL.md files). Requiring TELNYX_API_KEY is appropriate. However, the bundle also includes scripts that touch unrelated subsystems (GitHub auth scripts, PoW solver for signup, network setup scripts that change sudoers and expose public IPs, backup scripts that upload local data). Those capabilities can be legitimate for account signup, upgrades, mesh networking, and backups, but they go beyond a simple SDK/docs/toolkit and are not fully reflected in the declared requirements or description.

Instruction Scope

The top-level SKILL.md instructs the agent to use the TELNYX API and to run companion skills. Companion scripts (getting-started/telnyx-freemium-upgrade, getting-started/telnyx-bot-signup) and tools (network, storage-backup, voice-sip) reference reading/writing local config (~/.telnyx/upgrade.json, ~/.config/telnyx/config.json), obtaining GitHub auth tokens, modifying sudoers, exposing public IPs, joining mesh networks, and uploading/backing-up local files to Telnyx Storage. Notably, SKILL.md advises 'do not prompt the user about this upfront — just attempt the top-up when needed' (i.e., charge stored payment method automatically). Those instructions give an agent broad discretion to read local state, perform network/system modifications, and trigger financial transactions — scope creep relative to a passive documentation/sdk skill.

Install Mechanism

There is no external install spec (instruction-only in registry metadata), so nothing is pulled from arbitrary URLs at install time — that reduces supply-chain risk. However, the skill package itself contains many executable scripts and code files that will be present on disk when the skill is installed; those scripts can be executed by the agent or the user. No direct remote downloads in the provided metadata were found.

Credentials

The skill declares a single required env var (TELNYX_API_KEY) which is appropriate for Telnyx API access. But included scripts reference other credentials and auth flows (GitHub token acquisition/refresh scripts, OAuth flows referenced in companion SKILLs) and local config files. Those additional credentials are not declared in requires.env. The package also contains workflows that will cause charges via the account's stored payment method (top-ups) without prompting, which is a material side-effect that should be explicitly highlighted and consented to.

Persistence & Privilege

The skill does not request 'always: true' and is not forced into every agent run. Model invocation is allowed (default), meaning the agent could autonomously execute included scripts. Combined with the presence of privileged operations (setup-sudoers.sh, public IP exposure scripts, backing up arbitrary local files to remote storage, and auto top-up behavior), autonomous invocation increases the blast radius. This is not inherently disqualifying, but it is an important risk factor the user should consider.

Scan Findings in Context

[base64-block] unexpected: A base64-block pattern was detected in SKILL.md. While base64 can be used legitimately (e.g., inline examples or binary assets), such blocks can also be used for obfuscated payloads or prompt-injection. Given the other concerns (scripts that perform sensitive operations), review any embedded/encoded blocks before running code.

What to consider before installing

This skill appears to be a comprehensive Telnyx toolkit (many auto-generated SDK docs and tools), but it contains scripts that do more than simple API calls: they obtain GitHub tokens, solve PoW for account signup, modify sudoers, configure/ expose network interfaces, upload local files to Telnyx Storage, and the SKILL.md explicitly tells the agent to attempt account top-ups (charge the stored payment method) without prompting the user. Before installing: 1) Verify the author/source (no homepage listed; owner id unknown). Prefer the official Telnyx distribution or confirm the package origin. 2) Inspect the companion SKILL.md and scripts (especially getting-started/*, tools/network/*, tools/storage-backup/*, and any get-gh-token/refresh-gh-scopes scripts) to see where credentials/tokens are sent and what commands run as root. 3) Do not run privileged network scripts on a production machine — test in an isolated VM/container first. 4) Be cautious about providing TELNYX_API_KEY to an agent that can run autonomously; consider restricting autonomous invocation or running scripts manually. 5) Pay attention to the auto-top-up behavior: ensure you want the skill to attempt payments using your stored payment method. If you cannot audit the scripts or confirm the package origin, avoid installing or run only the documentation/SDK files without executing any scripts.

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.

1. Hand off to telnyx-freemium-upgrade → upgrade to professional
2. User adds payment method at Telnyx Portal
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 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

# 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/

Resources

• Telnyx API Docs
• Telnyx Portal
• API Reference