Telnyx Freemium Upgrade

Telnyx Professional Upgrade Skill

Companion Skills

This skill depends on telnyx-bot-signup for API key generation and refresh. If no Telnyx API key is available, or if the key needs to be refreshed after a successful upgrade, use telnyx-bot-signup to obtain one. The bot_signup endpoint handles both new and existing accounts — just provide the user's email.

When to Activate

This skill triggers when the bot encounters a freemium-blocked operation. Activate when ANY of these conditions occur:

Automatic Triggers (API Error Codes)

Heuristic Triggers (Capacity Limits)

• Phone number order fails after the first purchase (1 number limit)
• Balance/credit check returns low available credit ($10 ceiling)
• Inability to add funds / top up balance — freemium accounts cannot add balance or payment methods. If the bot encounters an error when trying to add funds, check account tier, or top up, and the account is freemium, this is a strong signal that an upgrade is needed.
• Account shows as "inactive" or "deactivated" due to $0 balance on freemium tier

Explicit Triggers

• User requests an upgrade: "upgrade my account", "I need professional tier"
• Bot needs a non-freemium feature: "send SMS to unverified number", "port a number", "create a managed account"
• User or bot tries to add balance/payment and is blocked by freemium restrictions

Verification Methods

Two verification methods are available. Each can only be used once per account.

Method Selection Decision Tree

Which method to try?
├── Check ~/.telnyx/upgrade.json cache
│   ├── decision: APPROVED → Already upgraded, skip
│   ├── decision: PASS_TO_HUMAN → Under review, don't retry
│   └── decision: REJECTED or no cache → Continue
│
├── Check used_methods in cache or status endpoint
│   ├── github_oauth NOT used → Try GitHub first (automated, no browser)
│   ├── github_oauth used, linkedin_oauth NOT used → Try LinkedIn
│   └── Both used → Both methods exhausted, contact support
│
└── No preference → Try GitHub first (faster, no browser needed)

LinkedIn Verification Method

When to use: User has no GitHub account, GitHub method was REJECTED, or user prefers LinkedIn.

Flow:

1. python3 {baseDir}/scripts/evaluate-upgrade.py --linkedin
   → Returns { action: "open_url", url: "<linkedin_oauth_url>" }

2. Present the URL to the user:
   "To verify your identity, please open this link and sign in with LinkedIn:
    <url>
    After authorizing, you can close the browser tab."

3. The script polls automatically. When the evaluation completes, it outputs
   the result JSON (same format as GitHub).

4. Handle outcome: APPROVED / REJECTED / PASS_TO_HUMAN (same as GitHub)

Notification templates for LinkedIn URL:

Telegram:

🔗 Telnyx Account Upgrade — LinkedIn Verification

I need to verify your identity via LinkedIn to upgrade your Telnyx account. This is a one-time step.

👉 Open: <URL>
⏰ Link expires in 10 minutes

Sign in with your LinkedIn account when prompted. After authorizing, you can close the tab.

Slack:

:link: *Telnyx Account Upgrade — LinkedIn Verification*

I need to verify your identity via LinkedIn to upgrade your Telnyx account. This is a one-time step.

:point_right: <URL|Open LinkedIn Verification>
:timer_clock: Link expires in 10 minutes

Sign in with your LinkedIn account when prompted. After authorizing, you can close the tab.

Pre-flight Checks (ALWAYS do these first)

Before submitting a new evaluation:

1. Check Local Cache

Read ~/.telnyx/upgrade.json. If it exists:

• decision: "APPROVED" → Skip evaluation entirely. The account is already upgraded. Retry the blocked operation directly.
• decision: "PASS_TO_HUMAN" → Re-poll the status endpoint with the cached evaluation_id to check if a decision was made. Do NOT submit a new evaluation.
• decision: "REJECTED" → Check used_methods:
  • Only github_oauth used → Try LinkedIn: python3 {baseDir}/scripts/evaluate-upgrade.py --linkedin
  • Only linkedin_oauth used → Try GitHub: python3 {baseDir}/scripts/evaluate-upgrade.py --github-token <TOKEN>
  • Both used → All methods exhausted. Contact support.
• status: "polling_timeout" → Re-poll the cached evaluation_id. The evaluation may have completed server-side.

2. Check used_methods via Status Endpoint

If no cache or cache is stale, poll GET /v2/account/upgrade-request-status/{evaluation_id} (if you have an evaluation_id) or check the latest evaluation. Check which methods have been used and follow the decision tree above.

Token Type Detection and Handling

Run {baseDir}/scripts/check-gh-auth.sh to get token info. Handle based on token_type:

ghs_ (GitHub App Installation Token) → ABORT

These tokens represent a GitHub App, NOT a human user. Cannot verify human identity.

Tell the user:

Your GitHub CLI is authenticated with a GitHub App installation token (commonly used in CI/CD environments). This token type cannot access user profile data needed for identity verification.

To proceed, please authenticate with your personal GitHub account:

gh auth login --web

This will not affect your CI/CD workflows — gh supports multiple accounts.

STOP — wait for user to re-authenticate, then retry.

github_pat_ (Fine-grained PAT) → WARN and PROCEED

Fine-grained PATs have limited API access: /user/orgs returns empty, no GraphQL support. Evaluation will have degraded data.

Tell the user:

Your GitHub CLI is using a fine-grained personal access token. Some profile data (organizations, GraphQL contributions) may be unavailable, which could affect your evaluation. For best results, run gh auth login --web to use a standard OAuth token.

PROCEED with the token anyway — the evaluator handles partial data.

gho_ or ghp_ (OAuth / Classic PAT) → CHECK SCOPES and PROCEED

These are compatible token types. Check scopes and refresh if needed.

Scope Check and Refresh

Required scopes: user, read:org

If check-gh-auth.sh returns missing_scopes that is non-empty:

1. Run {baseDir}/scripts/refresh-gh-scopes.sh

2. Check the output:

   • success: true → scopes refreshed without browser interaction. Continue to submission.
   • requires_browser: true + success: false → the device_code, verification_uri, and pid fields are returned. Deliver the device code to the user via the Notification Decision Tree below.

3. After the user authorizes, run {baseDir}/scripts/wait-for-auth.sh to confirm the refresh completed:

   • success: true → scopes refreshed. Continue to submission.
   • success: false → device code expired or authorization was denied. Retry from step 1 (max 3 times).

   You can also pass the PID directly: bash {baseDir}/scripts/wait-for-auth.sh --pid <PID>

Notification Decision Tree (Scope Refresh)

When the bot needs a scope refresh or token acquisition:

START: Bot needs GitHub scope refresh
│
├── Is `gh` installed?
│   ├── NO → Notify user: "Install gh: https://cli.github.com"
│   │        OR offer manual PAT creation via github.com/settings/tokens
│   │        INTERVENTION: MEDIUM
│   │
│   └── YES → Check token type (prefix)
│       │
│       ├── ghs_ (installation) → ABORT
│       │   Notify user: "Need personal GitHub auth, not CI/CD token"
│       │   INTERVENTION: MEDIUM
│       │
│       ├── github_pat_ (fine-grained) → WARN, proceed with degraded data
│       │   Cannot refresh scopes on PATs → proceed as-is
│       │   INTERVENTION: ZERO (but evaluation has less data)
│       │
│       └── gho_ / ghp_ (OAuth / classic PAT) → Check scopes
│           │
│           ├── Scopes OK → PROCEED directly to upgrade evaluation
│           │   INTERVENTION: ZERO
│           │
│           └── Scopes missing → Need refresh
│               │
│               └── Send device code to user's active channel
│                   │
│                   ├── User reachable on Telegram/Slack/etc?
│                   │   ├── YES → Send code + link (see Cross-Channel Notification)
│                   │   │   INTERVENTION: MINIMAL (user taps link, enters code)
│                   │   │
│                   │   └── NO (offline) → Save state + heartbeat
│                   │       INTERVENTION: DEFERRED

Cross-Channel Notification (Minimal Intervention)

Parse the device code from refresh-gh-scopes.sh output (device_code and verification_uri fields).

Send to the user's active channel:

Telegram:

🔑 Telnyx Account Upgrade

I need to verify your GitHub identity to upgrade your Telnyx account from freemium to professional tier. This is a one-time step.

👉 Visit: https://github.com/login/device
📝 Enter code: <DEVICE_CODE>
⏰ Expires in 15 minutes

Tap the link above to open in your browser. You must be logged into GitHub.

Slack:

:key: *Telnyx Account Upgrade*

I need to verify your GitHub identity to upgrade your Telnyx account. This is a one-time step.

:point_right: <https://github.com/login/device|Open GitHub Device Authorization>
:pencil: Enter code: `<DEVICE_CODE>`
:timer_clock: Expires in 15 minutes

You must be logged into GitHub in your browser.

SMS (last resort):

Telnyx upgrade: enter code <DEVICE_CODE> at github.com/login/device within 15 min. Must be logged into GitHub.

Use the user's last active channel (check OpenClaw config at ~/.openclaw/openclaw.json). Priority: Telegram > Slack > SMS.

Deferred (User Offline)

If the user is unreachable:

1. Save state to ~/.telnyx/upgrade.json:

   {
     "pending_action": "scope_refresh",
     "reason": "missing_scopes",
     "required_scopes": ["user", "read:org"],
     "queued_at": "<ISO_TIMESTAMP>",
     "original_task": "<description of what triggered the upgrade>"
   }

2. On user return (next message to bot), respond:

   Before we continue, I need to upgrade your Telnyx account to use [requested feature]. This requires a one-time GitHub verification. Ready to proceed?

Proactive Upgrade (Optional)

On first Telnyx API interaction or skill load, the bot MAY proactively check the account tier:

1. If freemium and no prior attempt:
   • If gho_ token with user scope already present → start upgrade silently in background. Notify user only on completion.
   • If scopes missing but token compatible → offer: "I notice you're on Telnyx's freemium tier. Some features you might need require an upgrade. I can handle this now (takes ~2 min, needs GitHub verification) or we can do it later when you actually need it. Want me to proceed?"
   • If gh not installed or ghs_ token → queue for later, don't interrupt.
2. If prior APPROVED → no action needed.
3. If prior REJECTED → inform only when user hits a freemium wall.
4. If prior PASS_TO_HUMAN → re-poll silently.

Intent Analysis (Before API Call)

The bot can analyze the user's intent before making a Telnyx API call to proactively trigger the upgrade:

API Key Resolution

The Telnyx API key is resolved in this order:

1. TELNYX_API_KEY environment variable — checked first
2. ~/.config/telnyx/config.json — fallback (written by telnyx auth setup from the telnyx-cli skill)

To read from the config file:

API_KEY="${TELNYX_API_KEY:-$(python3 -c "import json; print(json.load(open('$HOME/.config/telnyx/config.json'))['api_key'])" 2>/dev/null || echo '')}"

If neither source has a key, hand off to the telnyx-bot-signup skill to generate one. The bot_signup endpoint works for both new and existing accounts — it sends a magic sign-in link to the user's email and produces a fresh API key. If telnyx-bot-signup is not installed:

No Telnyx API key found. Install the signup skill (clawhub install telnyx-bot-signup) or set the TELNYX_API_KEY environment variable.

Submission and Polling

GitHub Method

Once the GitHub token is ready:

1. Resolve the Telnyx API key (see API Key Resolution above).
2. Run {baseDir}/scripts/get-gh-token.sh to extract the GitHub token.
3. Run {baseDir}/scripts/evaluate-upgrade.py --github-token <TOKEN> --api-key <API_KEY>
4. The script handles: submission → polling (every 5s, max 120s) → caching → structured output.

LinkedIn Method

1. Resolve the Telnyx API key (see API Key Resolution above).
2. Run {baseDir}/scripts/evaluate-upgrade.py --linkedin --api-key <API_KEY>
3. The script outputs an open_url action with the LinkedIn OAuth URL.
4. Present the URL to the user (see notification templates above).
5. The script automatically polls for the evaluation to appear and complete.
6. Output is the same JSON format as the GitHub method.

Response Templates (Per Outcome)

APPROVED

Your Telnyx account has been upgraded to the professional tier! Retrying your request...

Then retry the original blocked operation. 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) rather than asking the user to visit the portal.