telnyx-freemium-upgrade_skill

Overview

This skill automates upgrading a Telnyx account from freemium to the professional tier when a freemium restriction blocks an operation. It orchestrates verification flows (GitHub or LinkedIn), resolves API keys, and handles polling, caching, and user notifications to minimize manual steps. Use it to recover blocked features like SMS to unverified numbers, porting, or ordering more than one phone number.

How this skill works

The skill detects freemium-blocked operations via Telnyx error codes, capacity heuristics, or explicit user requests. It resolves the Telnyx API key, chooses an available verification method (GitHub first, then LinkedIn), submits an upgrade evaluation, polls for results, caches outcomes in ~/.telnyx/upgrade.json, and notifies the user or queues deferred actions as needed. It also handles GitHub token type and scope checks, prompting for device codes or browser-based OAuth when required.

When to use it

• When Telnyx API returns freemium error codes (10039, D60, 10038).
• When phone number ordering fails after the first purchase or balance/top-up is blocked.
• When a user explicitly requests: "upgrade my account" or needs professional features.
• When the bot needs to send SMS to unverified destinations, port numbers, or create managed accounts.
• As a proactive check before operations that require non-freemium capabilities.

Best practices

• Always run pre-flight checks: read ~/.telnyx/upgrade.json and poll status endpoints before submitting a new evaluation.
• Prefer GitHub verification first (automated, no browser) and fall back to LinkedIn only if needed or rejected.
• Resolve the Telnyx API key from TELNYX_API_KEY env var or ~/.config/telnyx/config.json before submission.
• Handle GitHub token types: abort on ghs_, warn on github_pat_, and refresh scopes for gho_/ghp_ when missing.
• Use the user's last active channel for device-code notifications (Telegram > Slack > SMS) and persist state if user is offline.

Example use cases

• Bot attempts to send SMS to an unverified number and receives error 10039 — auto-trigger upgrade workflow.
• User asks to buy five phone numbers — detect freemium limit and proactively offer upgrade.
• Payment or top-up is blocked on freemium — notify user and initiate upgrade evaluation.
• Silent background upgrade when a valid gho_ token with required scopes is already present.
• Fallback LinkedIn flow: present OAuth URL to the user when GitHub method was exhausted or not available.