Telnyx CLI

intent

this skill lets you interact with the Telnyx API through the command line to send messages across SMS, email, and WhatsApp, manage phone numbers, monitor webhooks, query call history, and check account balance. use it when you need to send bulk messages, search for available phone numbers, debug failed webhooks, or pull account data from Telnyx without touching the web portal.

inputs

required binaries:

• telnyx (npm global package: npm install -g @telnyx/api-cli)

required credentials:

• Telnyx API key stored in ~/.config/telnyx/config.json after running telnyx auth setup
• obtain the key from https://portal.telnyx.com/#/app/api-keys
• alternatively, set TELNYX_API_KEY environment variable for the current session

external connection:

• Telnyx REST API (https://developers.telnyx.com). requires network access and valid API key with appropriate scopes (messaging, calling, number management, webhooks).

companion skills for account lifecycle:

• telnyx-bot-signup: creates new Telnyx accounts or signs into existing ones. hand off when API key is missing, invalid (401 error), or user needs to generate a fresh key.
• telnyx-freemium-upgrade: upgrades freemium accounts to professional tier. hand off when CLI commands fail with error 10039 (unverified destination), error D60 (voice blocked), error 10038 (feature not available on current plan), or when you hit freemium limits (1 phone number max, cannot add funds).

procedure

0. pre-flight check (do this before any telnyx CLI command)

• input: none
• step: verify CLI is installed: npm list -g @telnyx/api-cli or attempt telnyx --version
• output: success (CLI present) or failure (CLI missing, proceed to step 0a)
• decision: if not found, run npm install -g @telnyx/api-cli and re-check

0a. verify API key exists and is valid

• input: none
• step: run telnyx account get to test authentication
• output: either (1) success with JSON account data, or (2) 401 auth error, or (3) network error
• decision: see decision points section below

1. send SMS/email/WhatsApp message

• input: sender phone number (or email for email), recipient phone number or email, message text, message type (sms/email/whatsapp)
• step: run telnyx message send --from <SENDER> --to <RECIPIENT> --text "<MESSAGE>" (or --email-from/--email-to for email, --whatsapp-from/--whatsapp-to for WhatsApp)
• output: message ID, status (queued, sent, failed), timestamp
• decision: see decision points for freemium or auth failures

2. list sent or received messages

• input: optional filters (date range, direction, status)
• step: run telnyx message list [--status sent|received] [--start-time TIMESTAMP] [--end-time TIMESTAMP]
• output: table or JSON array of message objects (ID, sender, recipient, text, status, timestamp)

3. get message status

• input: message ID
• step: run telnyx message get <MESSAGE_ID>
• output: detailed message object with status (queued, sent, failed, delivered), error code if failed, delivery receipt timestamp

4. list phone numbers owned by account

• input: none
• step: run telnyx number list [--limit N]
• output: table or JSON array of phone number objects (number, status, capabilities: voice/SMS/fax, country, cost per month, expiration date)

5. search for available phone numbers

• input: search criteria (country code, area code/NPA, number type: local/mobile/toll-free)
• step: run telnyx number search --country <COUNTRY> --npa <AREA_CODE> [--number-type local|mobile|toll-free]
• output: table or JSON array of available numbers, pricing per unit, availability

6. purchase a phone number

• input: phone number string (e.g., "+15551234567")
• step: run telnyx number buy --number "<PHONE_NUMBER>"
• output: confirmation with purchased number, status (active), monthly cost, activation timestamp
• decision: if purchase fails with "number no longer available", re-run search and select a different number

7. release a phone number

• input: phone number to release
• step: run telnyx number release "<PHONE_NUMBER>"
• output: confirmation with release timestamp; number reverts to available pool

8. list call logs

• input: optional filters (limit, direction inbound/outbound, status)
• step: run telnyx call list [--limit N] [--direction inbound|outbound]
• output: table or JSON array of call objects (ID, from, to, direction, status, duration, timestamp)

9. get call details

• input: call ID
• step: run telnyx call get <CALL_ID>
• output: detailed call object with all metadata (start time, end time, duration, status, recording URL if available, error code if failed)

10. list webhooks

• input: none
• step: run telnyx webhook list
• output: table or JSON array of webhook URLs, event types they subscribe to, status (active/inactive), creation date

11. view webhook delivery events (debugger)

• input: optional filter (--status succeeded|failed)
• step: run telnyx debugger list [--status failed] [--limit N]
• output: table or JSON array of webhook event objects (event ID, type, status, recipient URL, delivery timestamp, response code)

12. retry a failed webhook delivery

• input: webhook event ID
• step: run telnyx debugger retry <EVENT_ID>
• output: confirmation with new delivery attempt timestamp and result (success or new failure)

13. get account info and balance

• input: none
• step: run telnyx account get [--output json]
• output: account object with account ID, plan tier (freemium/professional), balance in cents, billing address, active phone numbers count

14. change output format

• input: any prior command and desired format (json/csv/table)
• step: append --output json or --output csv to any listing command
• output: same data in requested format (JSON, CSV, or human-readable table)

decision points

after pre-flight check (step 0a), determine next action:

• if telnyx account get returns 200 with account data: proceed to user's requested operation (steps 1-14).
• if telnyx account get returns 401 (Unauthorized): API key is invalid, expired, or revoked. hand off to telnyx-bot-signup (ask for email, generate fresh key, store in ~/.config/telnyx/config.json).
• if telnyx account get returns 4xx other than 401: API key exists but has a validation or permissions issue. retry with telnyx auth setup to reconfigure.
• if telnyx account get fails with network error (connection refused, timeout, DNS failure): check network connectivity and Telnyx API status. retry after 30 seconds.
• if no API key exists (file not found, no env var): hand off to telnyx-bot-signup.

during messaging, calling, or number operations, if operation fails, check error code:

• error 10039 (destination not verified) or error D60 (voice destination blocked): account is freemium and recipient country/number is not verified. check upgrade cache at ~/.telnyx/upgrade.json. if cache shows APPROVED, retry command (may need fresh API key from telnyx-bot-signup). if cache shows REJECTED, tell user upgrade was denied, suggest support. if cache missing or failed, hand off to telnyx-freemium-upgrade.
• error 10038 (feature not available on current plan): freemium account lacks this feature (e.g., porting, SIM, short codes, managed accounts). hand off to telnyx-freemium-upgrade.
• error on telnyx number buy saying number limit exceeded: freemium max is 1 number. hand off to telnyx-freemium-upgrade for upgrade.
• error on balance top-up or payment method: freemium accounts cannot add funds. hand off to telnyx-freemium-upgrade.
• 401 during operation: API key expired mid-session. hand off to telnyx-bot-signup for fresh key.
• rate limit error (429): Telnyx allows 100 req/s. add sleep 1 between requests in bulk scripts or implement exponential backoff.
• timeout on webhook/call list with large datasets: increase --limit or paginate. Telnyx CLI defaults to limit 100; max is 1000.

proactively trigger freemium upgrade before making API call if user intent clearly requires professional tier:

• user wants to send SMS to international number (outside US): likely unverified destination, hand off to upgrade first.
• user wants to port a phone number: porting is blocked on freemium, hand off to upgrade.
• user wants to buy multiple phone numbers (more than 1): freemium limit, hand off to upgrade.
• user wants to set up SIP trunk or managed account: professional-only features, hand off to upgrade.
• user wants to add credit/funds to account: freemium cannot load balance, hand off to upgrade.

output contract

all CLI commands return data in one of three formats:

table format (default):

• human-readable columns and rows
• suitable for terminal display
• example: telnyx number list prints phone numbers with country, status, cost columns

JSON format (append --output json):

• machine-parseable JSON object with data array and metadata
• structure: {"data": [<objects>], "metadata": {"total": N, "page": P}}
• suitable for piping to jq or storing in files
• example: telnyx account get --output json returns account object as valid JSON

CSV format (append --output csv):

• comma-separated values with header row
• suitable for import into spreadsheets or databases
• example: telnyx call list --output csv > calls.csv writes to file

file storage locations:

• API key: ~/.config/telnyx/config.json (JSON with {"api_key": "KEY_VALUE"})
• upgrade cache: ~/.telnyx/upgrade.json (set by companion skill, read by this skill to avoid redundant upgrades)

success response examples:

sending a message returns:

{
  "data": {
    "record_type": "message",
    "id": "msg_ABC123",
    "from": "+15551234567",
    "to": "+15559876543",
    "text": "Hello!",
    "status": "queued",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

listing numbers returns:

{
  "data": [
    {
      "record_type": "phone_number",
      "phone_number": "+15551234567",
      "status": "active",
      "country": "US",
      "capabilities": ["sms", "voice"],
      "monthly_cost": 1.25
    }
  ],
  "metadata": {"total": 1, "page": 1}
}

checking account returns:

{
  "data": {
    "record_type": "account",
    "id": "acc_XYZ789",
    "status": "active",
    "plan_tier": "freemium",
    "balance_cents": 5000,
    "phone_numbers_count": 1
  }
}

outcome signal

the skill worked if:

1. after install and setup: telnyx --version prints version number, and telnyx account get succeeds with 200 response and your account email visible in the output.

2. after sending a message: telnyx message send returns a message ID and status "queued" or "sent" within 2 seconds. check delivery with telnyx message get <ID> to confirm status changes to "sent" or "delivered" (SMS typically confirms within 5 seconds, email within 10 seconds).

3. after listing/searching numbers: output includes at least one row (for list) or multiple rows (for search). check that phone numbers are properly formatted (+country code and digits) and status is either "active" (for owned numbers) or "available" (for search results).

4. after purchasing a number: output shows the number with status "active" and a confirmation message. verify by running telnyx number list again and seeing the new number in the list.

5. after querying call logs: output includes call records with start/end times and durations in seconds. verify timestamps are recent and match your call activity.

6. after listing webhooks or debugger events: output shows webhook URLs or event records. if you previously sent webhooks, check that event count matches expected message or call volume.

7. after retrying a failed webhook: debugger output shows the event with new delivery timestamp and response code (should be 2xx if the retry succeeded).

8. bulk operations (loops, exports): all messages in the loop sent without rate limit errors (if looping with sleep 1). exported CSV or JSON files are valid (can open in spreadsheet or parse with jq).

9. troubleshooting commands work: telnyx auth setup completes without errors, API key is written to config file, and subsequent telnyx account get succeeds.

if any command returns 4xx or 5xx, check the error message. if it's 10039, 10038, D60, or mentions freemium, refer to decision points for upgrade flow. if it's 401, API key is stale; re-run telnyx auth setup. if it's a timeout or 5xx, retry after 10 seconds or check Telnyx status page.

---

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

category	command	description
messaging	telnyx message send	send SMS/email/WhatsApp
	telnyx message list	list messages
	telnyx message get	get message status
phone numbers	telnyx number list	your phone numbers
	telnyx number search	search available numbers
	telnyx number buy	purchase a number
	telnyx number release	release a number
calls	telnyx call list	view calls
	telnyx call get	get call details
webhooks	telnyx webhook list	list webhooks
	telnyx debugger list	view webhook events
	telnyx debugger retry	retry failed webhooks
account	telnyx account get	account info and balance

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 and 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 "WARNING: $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.
• for large queries (call list, message history), use --limit 1000 to fetch max results.
• webhook retries may take up to 5 seconds to process. check status with telnyx debugger list again if immediate recheck fails.

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 '.data.balance_cents')
echo "Balance: $BALANCE cents"

companion skills

this skill is the primary Telnyx interface. two companion skills handle account lifecycle operations that this skill cannot:

skill	purpose	install
telnyx-bot-signup	create a new account OR sign into an existing one (generates API key)	clawhub install telnyx-bot-signup
telnyx-freemium-upgrade	upgrade freemium account to professional tier	clawhub install telnyx-freemium-upgrade

note: telnyx-bot-signup handles both signup and signin. the bot_signup endpoint accepts both new and existing emails, sending 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 cannot 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":"<KEY_FROM_SIGNUP>"}' > ~/.config/telnyx/config.json
   

2. also export it for the current session:

   export TELNYX_API_KEY="<KEY_FROM_SIGNUP>"
   

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.

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:

trigger	how you see it	example
error 10039	SMS send fails: "destination not verified"	telnyx message send --to +39... --text "test"
error D60	voice call fails: "destination not verified"	outbound call to unverified number
error 10038	feature blocked: "not available on current plan"	porting, short codes, SIM, managed accounts
number limit hit	second telnyx number buy fails	already have 1 number (freemium max)
cannot add funds	balance top-up or payment method rejected	freemium accounts cannot add balance
account inactive/deactivated	account shows deactivated due to zero balance	telnyx account get shows inactive status

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

user says	why it needs upgrade
"send SMS to +39..." (international)	unverified destination (10039)
"port my number from AT&T"	porting blocked on freemium (10038)
"buy 5 phone numbers"	1 number limit on freemium
"set up a SIP trunk"	SIP blocked on freemium (10038)
"create a managed account"	managed accounts blocked (10038)
"add $50 to my balance"	freemium cannot add funds

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