/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. macOS ships bash 3.2 — scripts auto-upgrade via Homebrew bash if available (brew install bash)."

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 ALL user input (API key, phone number, cost approval). Phases 1–6 run **fully autonomously** — do NOT ask the user any questions. Make all decisions deterministically using the rules in each phase. The only exception: if a failure persists after 3 fix attempts, present the issue to the user with error details and what you tried.

**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**: Flat form-encoded → nested JSON under `data.payload`. See `{baseDir}/references/webhook-migration.md` 4. **Recording Defaults**: Single → dual-channel. Set `channels="single"` to match Twilio behavior.

---

Phase 0: Prerequisites (User Input — ONLY Interaction Point)

> **This is the ONLY phase that requires user interaction.** Collect all inputs now — Phases 1–6 run fully autonomously. Do not ask the user any further questions during migration unless you hit a failure you cannot resolve after 3 attempts. > > **Exit criteria**: `TELNYX_API_KEY` validates, user phone number collected, costs approved.

Step 0.1: Collect All Required Information

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

1. **`TELNYX_API_KEY`** — API key v2 from https://portal.telnyx.com/#/app/api-keys. If they don't have a Telnyx account yet, direct them to: create account (https://telnyx.com/sign-up), complete KYC, add payment method, then generate key. 2. **`TELNYX_TO_NUMBER`** — their personal phone number in E.164 format (e.g., `+15551234567`) for receiving test SMS/call/OTP during integration testing. 3. **Cost approval** — present this table and get explicit approval:

| Item | Cost | When Charged | |------|------|-------------| | Phone number (if account has none) | ~$1.00/month | Phase 5 integration tests | | Integration tests (SMS + voice + verify + lookup + fax) | ~$0.144 total | Phase 5 | | 10DLC registration (US A2P messaging only) | ~$19 | Phase 3 setup (only if applicable) | | Number porting | Free | Post-migration (optional) |

**Total estimated cost for most migrations: under $1.20.** 10DLC adds ~$19 if applicable. Individual paid actions still have `--confirm` gates in the scripts.

**Do not proceed until the user provides all three items.** This is the last time you will ask the user for input.

Step 0.2: Validate API Key & Initialize State

bash {baseDir}/scripts/migration-state.sh init <project-root>
export TELNYX_API_KEY="<user-provided-key>"
export TELNYX_TO_NUMBER="<user-provided-number>"
curl -s -H "Authorization: Bearer $TELNYX_API_KEY" https://api.telnyx.com/v2/balance

If validation fails, ask the user to check their key and try again. This is the only retry that requires user input.

**Phase 0 exit**: `bash {baseDir}/scripts/migration-state.sh set-phase <project-root> 0`

---

Phase 1: Discovery

> **Prerequisites**: Phase 0 complete (`TELNYX_API_KEY` valid, phone number collected, costs approved). > **Exit criteria**: `twilio-scan.json` exists with scan results, migration scope determined.

Step 1.1: Run Full Discovery

Run the discovery script — this executes preflight check, Twilio scan, deep scan, and partial migration check in one command:

bash {baseDir}/scripts/run-discovery.sh <project-root>

This produces `<project-root>/twilio-scan.json` (and optionally `twilio-deep-scan.json`).

**You must run this script.** Do not manually scan files or skip this step.

Step 1.2: Triage and Determine Scope (Autonomous)

Review scan results and classify each match:

• **Active import/SDK call** (e.g., `from twilio.rest import Client`, `client.messages.create()`): Needs migration
• **String reference** (e.g., `# formerly used Twilio`, URL