Telnyx CLI：管理短信、语音和号码 - Openclaw Skills

什么是 Telnyx CLI？

Telnyx CLI 技能在 Telnyx API 与您的自动化环境之间搭建了一座坚实的桥梁。它使开发人员能够直接通过终端界面处理从发送 WhatsApp 消息到管理复杂的 Webhook 调试等各项事务。通过将其集成到您的 Openclaw Skills 集合中，您可以编写通信工作流脚本、监控账户余额，并在不离开开发环境的情况下自动化号码采购。

该技能专为高效运营而设计，支持 JSON 和 CSV 等多种输出格式，便于数据流水线处理。无论您是在构建自动化通知系统，还是管理大量的虚拟电话号码，Openclaw Skills 工具包中的这一补充都能确保可靠且可扩展的通信管理。

下载入口:https://github.com/openclaw/skills/tree/main/skills/teamtelnyx/telnyx-cli

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

npx clawhub@latest install telnyx-cli

2. 手动安装

将技能文件夹复制到以下位置之一

全局模式 ~/.openclaw/skills/ 工作区 /skills/

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

请帮我使用 Clawhub 安装 telnyx-cli。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。

Telnyx CLI 应用场景

• 自动化发送短信、电子邮件和 WhatsApp 通知。
• 通过编程方式搜索和购买本地或国际电话号码。
• 监控并重试失败的 Webhook 投递，适用于高可靠性应用。
• 导出通话记录和消息历史记录，用于合规性或数据分析。
• 编写具有内置速率限制的批量消息操作脚本。

Telnyx CLI 工作原理

1. 该技能利用 Telnyx API CLI 二进制文件与全球通信基础设施进行交互。
2. 用户通过安全的 API 密钥进行身份验证，该密钥本地存储在持久配置文件中。
3. 向 Telnyx API 发送命令以执行发送消息或查询账户元数据等操作。
4. 该技能会检查账户级别的限制，并可以自动将任务移交给专门的 Openclaw Skills 以进行注册或等级升级。
5. 结果以结构化格式返回，允许 AI 代理或 Shell 脚本进行进一步处理。

Telnyx CLI 配置指南

要开始使用此技能，请确保已安装 Node.js，然后运行以下命令安装 CLI 并配置您的凭据：

npm install -g @telnyx/api-cli
telnyx auth setup

系统将提示您输入 Telnyx Portal 中的 API 密钥。配置完成后，通过列出您的号码来验证安装：

telnyx number list

Telnyx CLI 数据架构与分类体系

该技能管理其配置并以多种结构化格式提供数据，以确保与其他 Openclaw Skills 和工具的兼容性：

组件	路径 / 格式	用途
身份验证	~/.config/telnyx/config.json	存储持久 API 密钥
升级缓存	~/.telnyx/upgrade.json	跟踪账户等级状态和升级决策
命令输出	JSON, CSV, 表格	短信、通话和号码的灵活数据格式
元数据	YAML	用于代理集成的技能特定定义

name: telnyx-cli
description: "Telnyx API integration for Clawdbot. Send SMS/email/WhatsApp messages, manage phone numbers, query call logs, debug webhooks, and access your Telnyx account. Use when you need to interact with Telnyx APIs via CLI, manage phone numbers and messaging, debug webhooks, or access account data."
metadata:
  clawdbot:
    emoji: "??"
    requires:
      bins: ["telnyx"]
      env: []
    notes: "API key stored in ~/.config/telnyx/config.json after 'telnyx auth setup'"

Telnyx CLI

Telnyx API integration for Clawdbot: messaging, phone numbers, webhooks, and account management.

Setup

1. Install CLI

npm install -g @telnyx/api-cli

2. Configure API Key

telnyx auth setup

Paste your API key from: https://portal.telnyx.com/#/app/api-keys

Saves to ~/.config/telnyx/config.json (persistent).

3. Verify

telnyx number list

Commands

Usage

Messaging

# Send SMS
telnyx message send --from +15551234567 --to +15559876543 --text "Hello!"

# List messages
telnyx message list

# Get status
telnyx message get MESSAGE_ID

Phone Numbers

# List
telnyx number list

# Search
telnyx number search --country US --npa 415

# Buy
telnyx number buy --number "+15551234567"

# Release
telnyx number release "+15551234567"

Webhooks & Debugging

# List webhooks
telnyx webhook list

# View failed deliveries
telnyx debugger list --status failed

# Retry failed
telnyx debugger retry EVENT_ID

Account

# Account info
telnyx account get

# Check balance
telnyx account get --output json | jq '.balance'

Output Formats

# Table (default)
telnyx number list

# JSON
telnyx number list --output json

# CSV
telnyx number list --output csv

Examples

Bulk Messaging

#!/bin/bash
while read phone; do
  telnyx message send --from +15551234567 --to "$phone" --text "Hello!"
  sleep 1  # Rate limiting
done < recipients.txt

Monitor Webhooks

#!/bin/bash
while true; do
  FAILED=$(telnyx debugger list --status failed --output json | jq '.data | length')
  [ "$FAILED" -gt 0 ] && echo "??  $FAILED failed webhooks"
  sleep 300
done

Export Data

# CSV export
telnyx call list --limit 1000 --output csv > calls.csv

# JSON export
telnyx number list --output json > numbers.json

Tips

• Rate limit: 100 req/s — add sleep 1 for bulk operations
• Use --output json or --output csv to change format
• Get help: telnyx COMMAND --help (e.g., telnyx message --help)
• API Key location: ~/.config/telnyx/config.json

Integration with Clawdbot

# In cron jobs
0 9 * * * telnyx call list --limit 10 > /tmp/daily-calls.txt

# In heartbeat
telnyx debugger list --status failed

# In scripts
BALANCE=$(telnyx account get --output json | jq '.balance')
echo "Balance: $BALANCE"

Companion Skills

This skill is the primary Telnyx interface. Two companion skills handle account lifecycle steps that this skill cannot:

Note: telnyx-bot-signup handles both signup and signin. The bot_signup endpoint accepts both new and existing emails — it sends a magic sign-in link either way. The flow is identical: PoW challenge → email → magic link → session token → API key.

Pre-flight: Before Any Telnyx Operation

Before executing a Telnyx CLI command, run through this checklist:

1. Is `telnyx` CLI installed?
   NO  → npm install -g @telnyx/api-cli

2. Does ~/.config/telnyx/config.json exist with an api_key?
   NO  → Hand off to **telnyx-bot-signup** (see below)
         Works for both new AND existing accounts.

3. Does `telnyx account get` succeed?
   NO (401 auth error)  → API key is invalid/expired.
                           Hand off to **telnyx-bot-signup** to generate a fresh key.
   NO (network error)   → Check connectivity.
   YES                  → Proceed with the requested operation.

When to Hand Off to telnyx-bot-signup

Hand off to the telnyx-bot-signup skill when ANY of these are true:

• No API key exists (~/.config/telnyx/config.json missing or empty, no TELNYX_API_KEY env var)
• API key exists but telnyx account get returns 401 (key invalid/expired/revoked)
• User says they lost their API key or can't access the portal
• User wants to create a new Telnyx account

Do NOT ask whether the user has an account or not. The bot_signup endpoint handles both cases transparently — just ask for their email and proceed.

What telnyx-bot-signup does: PoW challenge → submit email → magic sign-in link sent to email → session token → POST /v2/api_keys → fresh API key. Works identically for new and existing accounts.

After signup/signin completes:

1. Store the returned API key:

   mkdir -p ~/.config/telnyx
   echo '{"api_key":""}' > ~/.config/telnyx/config.json
   

2. Also export it for the current session:

   export TELNYX_API_KEY=""
   

3. If the account is new, it starts on freemium tier. Return here and proceed with the original operation. If it hits a freemium wall, the upgrade flow below will trigger automatically.

When to Hand Off to telnyx-freemium-upgrade

Hand off to the telnyx-freemium-upgrade skill when a CLI command fails with a freemium restriction. Detect these scenarios:

Also trigger proactively when the user's intent clearly requires professional tier before even making the API call:

Before handing off, check if the upgrade was already attempted:

1. Read ~/.telnyx/upgrade.json (cache from the upgrade skill)

2. If decision == "APPROVED"
   → Account is already upgraded. Do NOT hand off.
     Retry the operation directly. If it still fails, the API key
     may need to be refreshed: telnyx auth setup

3. If decision == "REJECTED" and used_methods includes "github_oauth"
   → GitHub method exhausted. Do NOT hand off.
     Tell the user: "Your upgrade was not approved. Contact
     support at https://support.telnyx.com or try LinkedIn
     verification when available."

4. If decision == "PASS_TO_HUMAN"
   → Under manual review. Do NOT hand off.
     Tell the user: "Your upgrade is under review. I'll check
     back periodically." (The upgrade skill's cron job handles this.)

5. If no cache or status is "failed" / "polling_timeout"
   → Hand off to **telnyx-freemium-upgrade**.

After upgrade completes (APPROVED):

1. Retry the original operation that triggered the upgrade.

2. If the retry still fails with the same error, the API key needs to be refreshed to pick up professional-tier permissions. Use telnyx-bot-signup to generate a fresh key (same email, sign-in flow) — this is easier than asking the user to visit the portal.

Full Lifecycle Flow

User: "Send SMS to +393406879636"
│
├── telnyx CLI installed? ──NO──→ npm install -g @telnyx/api-cli
│
├── API key configured? ──NO──→ **telnyx-bot-signup** (ask for email)
│                                 → PoW → magic link → API key
│                                 → Store key → continue
│
├── API key valid? (`telnyx account get`)
│   └── NO (401) → **telnyx-bot-signup** (ask for email)
│                   → PoW → magic link → fresh API key
│                   → Store key → continue
│
├── telnyx message send --from ... --to +39... --text "..."
│   │
│   ├── Success → Done
│   │
│   └── Error 10039 (destination not verified)
│       │
│       ├── Check upgrade cache (~/.telnyx/upgrade.json)
│       │   ├── APPROVED → Retry (key may need refresh)
│       │   ├── REJECTED → Inform user, suggest support
│       │   ├── PASS_TO_HUMAN → Inform user, wait for review
│       │   └── No cache / failed → Continue to upgrade
│       │
│       └── **telnyx-freemium-upgrade** → GitHub verification → poll
│           │
│           ├── APPROVED → retry SMS (key may need refresh via bot-signup)
│           ├── REJECTED → Inform user
│           └── PASS_TO_HUMAN → Cron job polls, notify on resolution

Companion Skill Not Installed

If you need to hand off but the companion skill is not installed:

telnyx-bot-signup missing:

I need to set up your Telnyx API key. Install the signup/signin skill:

clawhub install telnyx-bot-signup

Or get your API key manually from https://portal.telnyx.com/#/app/api-keys and run telnyx auth setup

telnyx-freemium-upgrade missing:

Your account is on the freemium tier, which doesn't support this operation. Install the upgrade skill:

clawhub install telnyx-freemium-upgrade

Or upgrade manually via https://portal.telnyx.com/#/account/account-levels/upgrade

---

Troubleshooting

CLI not found

npm install -g @telnyx/api-cli

API key not configured

# Reconfigure
telnyx auth setup

# Or check existing config
cat ~/.config/telnyx/config.json

Connection issues

# Test connection
telnyx account get

Resources

• Telnyx Docs: https://developers.telnyx.com
• API Portal: https://portal.telnyx.com
• Telnyx CLI: https://github.com/team-telnyx/telnyx-api-cli