/telnyx-twilio-migration

name: telnyx-twilio-migration
description: >-
  Migrate from Twilio to Telnyx. Orchestrates a complete 6-phase migration:
  discovery, planning, setup, code migration, validation, and cleanup.
  Covers voice (TwiML to TeXML, Call Control API), messaging, WebRTC,
  SIP trunking, verify, fax, video, IoT, number lookup, and porting.
  Includes automated scanners, validation scripts, and integration tests.
user_invocable: true
metadata:
  author: telnyx
  product: migration
  compatibility: "Requires bash 4+, jq, curl, python3. macOS ships bash 3.2 — scripts auto-upgrade via Homebrew bash if available (brew install bash). python3 is mandatory: the scanners and the correctness linter exit 2 without it."

Twilio to Telnyx Migration

> **Path convention:** `{baseDir}` in this document is the directory containing this `SKILL.md` file (e.g., `/path/to/skills/telnyx-twilio-migration`). Substitute the absolute path before running any script shown below — do not pass the literal string `{baseDir}` to bash.

You MUST follow these phases in order (0 → 1 → 2 → 3 → 4 → 5 → 6). Do NOT skip phases. Each phase has prerequisites and exit criteria — do not proceed until the exit criteria are met. You MUST run the scripts specified in each phase (do not substitute your own checks). You MUST modify the user's source files to complete the migration.

**Interaction model**: Phase 0 collects confirmation that `TELNYX_API_KEY` is set securely, the destinations required by the products in scope, an ISO-2 country for each destination (or explicit opt-in to a billed lookup), and an approved maximum spend based on a current price check. A live WebRTC-to-PSTN call requires its own opt-in. Never ask the user to paste an API key into chat. Phases 1–6 run autonomously except for one scoped Phase-1 decision if discovery finds unsupported products, a new or increased paid-action approval, and a failure that persists after 3 fix attempts.

**Context recovery**: If you lose context (e.g. after compaction), IMMEDIATELY run `bash {baseDir}/scripts/migration-state.sh status <project-root>` and `bash {baseDir}/scripts/migration-state.sh show <project-root>` to recover your current phase and all resource IDs. Then resume from that phase.

Migration State Tracking

Track progress in `migration-state.json` via `bash {baseDir}/scripts/migration-state.sh <command> <project-root> [args]`. Commands: `init`, `set-phase <N>`, `set <key> <value>`, `add-product <product>`, `add-file <product> <file>`, `set-commit <phase>`, `status`, `show`. This preserves resource IDs across phases and enables resume after interruption. For a complete product mapping, see `{baseDir}/references/product-mapping.md`.

Universal Changes (All Migrations)

1. **Authentication**: Basic Auth (`AccountSID:AuthToken`) → Bearer Token (`Authorization: Bearer $TELNYX_API_KEY`). Get key at https://portal.telnyx.com/#/app/api-keys 2. **Webhook Signatures**: HMAC-SHA1 → Ed25519. Get public key at https://portal.telnyx.com/#/app/account/public-key 3. **Webhook Payloads**: Messaging and Call Control move from flat form data to nested JSON under `data.payload`; TeXML callbacks remain form-encoded. See `{baseDir}/references/webhook-migration.md`. 4. **Recording Defaults**: TeXML `<Record>` defaults to dual-channel. Set `channels="single"` when the Twilio flow expects mono. `<Dial recordingChannels>` defaults to `single` and `recordMaxLength` defaults to `0`, as documented in the [Telnyx `<Dial>` reference](https://developers.telnyx.com/docs/voice/programmable-voice/texml-verbs/dial).

---

Phase 0: Prerequisites (Primary User-Input Phase)

> **This is the primary input phase.** Collect prerequisites now. Later interaction is limited to the bundled unsupported-product decision, approval for a new or increased paid action, or a failure that persists after 3 attempts. > > **Exit criteria**: `TELNYX_API_KEY` validates; every applicable product destination and its ISO-2 country (or billed-lookup opt-in) are recorded; current prices were checked; the user approved a maximum total charge and currency for the paid tests in scope; and the WebRTC live-call choice is recorded separately.

Step 0.1: Collect All Required Information

Ask the user for these **five things** in a single message:

1. **Secure API-key setup confirmation** — ask them to set `TELNYX_API_KEY` in their own local environment or secret store and reply only when it is present. Never request, display, log, or repeat the key value. If they do not have an account, direct them to https://telnyx.com/sign-up and https://portal.telnyx.com/#/app/api-keys. KYC and a payment method may still be required before paid capabilities. 2. **Product-specific destinations** — collect E.164 values only for products that will be tested:

• `TELNYX_TO_NUMBER` for messaging, voice, Verify, and an optional WebRTC live call.
• `TELNYX_FAX_TO` as a distinct, confirmed fax-capable destination when fax is in scope. Never assume the common SMS/voice test number receives faxes.
• `TELNYX_LOOKUP_NUMBER` only when Number Lookup should target a different number; otherwise the lookup script falls back to `TELNYX_TO_NUMBER`.

3. **Country resolution** — collect the destination's ISO 3166-1 alpha-2 code alongside every destination. The scripts use `TELNYX_TO_COUNTRY`, so export the code that matches the destination immediately before each test. If the user cannot provide it, obtain explicit approval for the billed Number Lookup and set `TELNYX_ALLOW_COUNTRY_LOOKUP=yes`; count that lookup against the approved maximum. Dry runs never perform this lookup implicitly. 4. **Paid-test approval** — check the [current Telnyx pricing](https://telnyx.com/pricing/) for each exact product, destination, routing type, and account-specific rate before quoting a test. Present the estimated charge for each paid action and a maximum total charge with its currency, then obtain explicit approval for that maximum. Price strings printed by test