Telnyx Twilio Migration

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.

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 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 scripts are non-binding examples, not quotes; --confirm is an execution guard and does not replace the price check or spend approval. If a current price is unavailable or the possible charge cannot be bounded, do not run the paid action. Phone-number purchase, 10DLC registration/vetting, and porting are separate workflows that require their own current quote and explicit approval; Phase 5 tests never purchase persistent numbers.
5. WebRTC live-call decision — the default WebRTC test validates credentials and token issuance without placing a PSTN call. A live call is a separate paid action: check its current price, obtain explicit approval under the maximum spend, and set TELNYX_WEBRTC_LIVE_CALL=yes only when the user opts in.

Do not proceed until the user confirms every applicable item. If unsupported products are discovered later, use the one scoped Phase-1 decision described below. If later discovery adds a paid product or changes the quoted maximum, stop and obtain an updated approval before that action.

Step 0.2: Validate API Key & Initialize State

bash {baseDir}/scripts/migration-state.sh init <project-root>
test -n "${TELNYX_API_KEY:-}" || { echo "Set TELNYX_API_KEY securely in your local environment" >&2; exit 1; }
# Record the non-secret approval boundary for recovery/audit; use the exact values the user approved.
bash {baseDir}/scripts/migration-state.sh set <project-root> approvals.paid_test_scope "<product-list>"
bash {baseDir}/scripts/migration-state.sh set <project-root> approvals.maximum_charge "<amount>"
bash {baseDir}/scripts/migration-state.sh set <project-root> approvals.currency "<ISO-4217-code>"
bash {baseDir}/scripts/migration-state.sh set <project-root> approvals.webrtc_live_call "<true-or-false>"
export TELNYX_TO_NUMBER="<user-provided-number>"
# Before each destination-scoped test, set the ISO-2 code that matches that test's destination:
export TELNYX_TO_COUNTRY="US"
# Set only when the corresponding product/destination is in scope:
export TELNYX_FAX_TO="<user-provided-fax-capable-number>"
export TELNYX_LOOKUP_NUMBER="<user-provided-lookup-number>"
# Set only after the separate approvals described above:
# export TELNYX_ALLOW_COUNTRY_LOOKUP=yes
# export TELNYX_WEBRTC_LIVE_CALL=yes
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; applicable destinations and country-resolution choices recorded; current-price estimates and a maximum spend approved; WebRTC live-call choice recorded). 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

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 in docs, log message): Usually no code change needed — just update text
• Config/env var (e.g., TWILIO_ACCOUNT_SID): Needs env var rename (see Phase 3)
• Test mock (e.g., mock_twilio_response): Migrate in Phase 4 alongside product code

Migrate all detected supported Twilio products. Apply these rules:

• Supported products (voice, messaging, verify, webrtc, sip, fax, video, lookup, numbers, porting, pay): migrate — <Pay> is implemented by the TeXML runtime and has a dedicated public verb reference (see references/texml-verbs.md); never drop or externalize in-call payment flows
• Unsupported products (Flex, Studio, TaskRouter, Conversations, Sync, Notify, Proxy, Autopilot): present all detected products and the alternatives from references/unsupported-products.md in one bundled decision. Ask whether each should be kept on Twilio, replaced, or removed. Do not modify or remove unsupported-product code before that answer. Record each decision in state, for example:

# Example after the user chooses to keep a product on Twilio:
bash {baseDir}/scripts/migration-state.sh set <project-root> kept_on_twilio.<product> true

See {baseDir}/references/unsupported-products.md for alternatives to note in the migration report.

Mobile platforms (detected and guided): iOS native, Android native, React Native, Flutter. These require client-side SDK migration — see {baseDir}/references/mobile-sdk-migration.md for complete migration guides.

Phase 1 exit: bash {baseDir}/scripts/migration-state.sh set-phase <project-root> 1 && bash {baseDir}/scripts/migration-state.sh set <project-root> scan_file "twilio-scan.json"

Phase 2: Planning

Prerequisites: Phase 1 complete, twilio-scan.json exists, scope determined. Exit criteria: MIGRATION-PLAN.md exists in project root.

Step 2.1: Read Relevant References

For each product detected in the scan, read the corresponding reference file:

Step 2.2: Apply Decision Matrix (Autonomous)

Do NOT ask the user to choose. Apply these rules deterministically:

Voice approach — select automatically based on the codebase:

Migration strategy — select automatically:

Step 2.3: Generate Migration Plan

cp {baseDir}/templates/MIGRATION-PLAN.md <project-root>/MIGRATION-PLAN.md

Populate the plan based on the decisions above. Do not ask for user approval — proceed directly to Phase 3.

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

Phase 3: Setup

Prerequisites: Phase 2 complete, MIGRATION-PLAN.md exists. Exit criteria: Telnyx SDK installed, environment variables updated, setup committed to git.

Step 3.1: Create Migration Branch

cd <project-root> && git checkout -b migrate/twilio-to-telnyx

Step 3.2: Install Telnyx SDK (Keep Twilio Until Phase 6)

Install Telnyx SDK alongside Twilio — do NOT remove Twilio from the package manifest yet (removal is Phase 6). Keep twilio in requirements.txt/package.json/Gemfile/go.mod, or com.twilio.sdk:twilio in pom.xml/build.gradle, until Phase 6 so you can revert if validation fails.

Server SDKs — use these EXACT commands with version constraints (do NOT use pip install telnyx or npm install telnyx without a version range):

• Python: pip install 'telnyx>=4.0,<5.0' — and write telnyx>=4.0,<5.0 in requirements.txt (NOT just telnyx). Initialize with from telnyx import Telnyx; client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY")).
• Node: npm install telnyx@^6 ws@^8 — writes "telnyx": "^6.x.x" in package.json automatically. Initialize with const Telnyx = require('telnyx'); const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY }); (CJS) or import Telnyx from 'telnyx' (ESM).
  • ws is required. telnyx@6 declares ws as an optional peer dependency (npm 10 skips optional peers), but resources/index.js unconditionally loads text-to-speech → require('ws'). Installing telnyx@^6 alone therefore produces an SDK that throws Error: Cannot find module 'ws' on the very first require('telnyx'). Always install ws alongside it.
• Ruby: gem 'telnyx', '~> 5.0' in Gemfile + bundle install
• Go: go get github.com/team-telnyx/telnyx-go/v4
• Java: Use the official Telnyx Java SDK. Read {baseDir}/sdk-reference/java/{product}.md for the pinned Maven/Gradle dependency and exact SDK examples.
• PHP: An official SDK is available, but this skill does not yet bundle PHP reference examples. Use the official SDK documentation or the REST examples in {baseDir}/sdk-reference/curl/.
• C#/.NET: No official server SDK is currently listed — use REST API with {baseDir}/sdk-reference/curl/ for API examples

Client-side WebRTC SDK (if WebRTC detected): npm install @telnyx/webrtc — see {baseDir}/sdk-reference/webrtc-client/javascript.md for the full API reference

Bundled language references: Python, JavaScript/TypeScript, Go, Ruby, and Java have full SDK examples in {baseDir}/sdk-reference/{lang}/. PHP uses the official SDK documentation or {baseDir}/sdk-reference/curl/; C#/.NET uses REST/curl. Client-side WebRTC SDKs exist for Swift (iOS), Kotlin (Android), React Native, and Flutter — see {baseDir}/references/mobile-sdk-migration.md.

JavaScript module warning: The sdk-reference/javascript/ files use ESM syntax (import Telnyx from 'telnyx'). If the project uses CommonJS (require), translate to: const Telnyx = require('telnyx'); const client = new Telnyx({ apiKey: process.env.TELNYX_API_KEY });. Do NOT copy ESM imports into CJS files unless "type": "module" is in package.json.

Step 3.3: Update Environment Variables

TELNYX_CONNECTION_ID disambiguation — all three are different Telnyx resources:

• TeXML: This is a TeXML Application ID from POST /v2/texml_applications. It owns your webhook URLs and outbound calling config.
• Call Control: This is a Call Control Application ID from POST /v2/call_control_applications. It routes inbound call events to your webhook.
• SIP trunking: This is a SIP Connection ID from POST /v2/credential_connections or POST /v2/ip_connections. It's used for PBX/SBC trunking.

Use a single TELNYX_CONNECTION_ID env var — its value is whichever ID matches your voice approach. If the app uses multiple approaches (e.g., TeXML for inbound + SIP for trunking), use separate env vars with descriptive names like TELNYX_TEXML_APP_ID and TELNYX_SIP_CONNECTION_ID.

Update .env, .env.example, secrets manager, CI/CD variables, and deployment configs. Ensure every env var used in the migrated code is present in .env.example — missing env vars are a top cause of runtime failures.

Destination allowlists (CRITICAL): Determine the target countries as ISO 3166-1 alpha-2 codes before creating Telnyx resources. Use explicit countries by default; use ["*"] only after an explicit decision to allow every destination. Without the correct allowlist, sends and calls fail.

• Messaging profiles: set whitelisted_destinations on the profile itself.
• Outbound Voice Profiles (OVP): set whitelisted_destinations, then assign the OVP to the Call Control or TeXML application's outbound.outbound_voice_profile_id.
• Verify profiles: set sms.whitelisted_destinations inside the SMS channel configuration.
• New run-owned resources: create them with only the destinations needed for the test or migration.
• Existing resources: inspect only. Never expand a Messaging Profile, OVP, or Verify Profile allowlist without an explicit opt-in naming the resource and countries. A PATCH /v2/outbound_voice_profiles/{id} request must also include the existing OVP name.
• --dry-run is read-only. Test scripts must fail with remediation instead of changing an existing resource unless the product-specific opt-in and --confirm are both present.

Rate limits: Messaging throughput varies by sender type, country, campaign, carrier, and vetting level; 10DLC is not a fixed 1 MPS. Respect current profile/campaign limits and Telnyx rate-limit response headers, queue traffic, and implement exponential backoff for 429 responses. Voice limits also vary by connection type.

Step 3.4: Commit Setup Changes

git add <changed-files> && git commit -m "chore: add Telnyx SDK alongside Twilio, update env vars"
bash {baseDir}/scripts/migration-state.sh set-phase <project-root> 3
bash {baseDir}/scripts/migration-state.sh set-commit <project-root> 3

Phase 4: Migration

Prerequisites: Phase 3 complete, Telnyx SDK installed, env vars updated, setup committed. Exit criteria: All source files transformed, per-product validation passes, all changes committed.

Transform code file-by-file, grouped by product area. You must actually modify the user's source files — reading references alone is not sufficient.

Migration Loop

Process each product area in priority order: messaging → voice → verify → numbers → others.

For each product area:

1. Read {baseDir}/references/{product}-migration.md — this is the primary source with Twilio→Telnyx before/after code, parameter mappings, and pitfall warnings
2. Collect all files for this product from the scan manifest (twilio-scan.json)

For each file in the product area:

1. Read the user's source file
2. Identify every Twilio pattern (imports, client init, API calls, webhooks, env vars)
3. Transform each pattern using the reference guide's before/after examples
4. If the reference doesn't cover a specific API call, look it up in {baseDir}/sdk-reference/{language}/{product}.md for the exact Telnyx method signature. The {baseDir}/sdk-reference/curl/{product}.md files have the richest examples with optional fields.
5. Write the transformed file
6. Self-check: Re-read the file and verify no Twilio patterns remain

After all source files in the product area:

7. Migrate tests: Find ALL test files for this product — grep -rl -i "twilio\|TwilioVoice\|TwilioClient\|twilio_" *test* *Test* *spec* *Spec* 2>/dev/null. Migrate every one: update imports, mock objects, mock payloads, assertions, and type references. Do NOT defer test files as "remaining manual steps" — they are part of the migration. Run the test suite to confirm.
8. Lint: bash {baseDir}/scripts/lint-telnyx-correctness.sh <project-root> --product {product} — catches common anti-patterns (wrong method names, wrong parameter names, missing profile IDs). Fix all ISSUE items before proceeding.
9. Validate: bash {baseDir}/scripts/validate-migration.sh <project-root> --product {product} --scan-json <project-root>/twilio-scan.json
10. Fix any validation failures or lint issues, re-run until both exit code 0
11. Commit: git add <changed-files> && git commit -m "migrate: {product} — Twilio to Telnyx"
12. Track: bash {baseDir}/scripts/migration-state.sh add-product <project-root> {product} (and add-file for each file migrated)

After ALL product areas are migrated:

13. Env var audit: Grep all migrated source files for process.env.TELNYX_ / os.environ["TELNYX_"] / ENV["TELNYX_"] references. Verify EVERY referenced env var exists in .env.example (or equivalent config template). Missing env vars are the #1 cause of "works in dev, fails in prod" bugs.

Post-Migration Documentation Update (MANDATORY)

After ALL product areas are migrated and committed, you MUST update documentation. This is NOT optional — agents that skip this step produce incomplete migrations.

1. Find all docs: grep -rl -i "twilio" README.md README CONTRIBUTING.md docs/ *.md 2>/dev/null (in project root)
2. Update each file — replace ALL of the following:
   • Project description: "uses Twilio" → "uses Telnyx"
   • Account setup instructions: Twilio Console → Telnyx Mission Control Portal (portal.telnyx.com)
   • API key generation: "Twilio Account SID and Auth Token" → "Telnyx API Key v2 from portal.telnyx.com/#/app/api-keys"
   • Environment variable names: every TWILIO_* → its TELNYX_* equivalent (see Phase 3 env var table)
   • API endpoint URLs: api.twilio.com → api.telnyx.com/v2
   • SDK install commands: pip install twilio → pip install 'telnyx>=4.0,<5.0', npm install twilio → npm install telnyx@^6 ws@^8 (the ws peer is required — see Phase 3), etc.
   • Webhook setup instructions: update signature verification method
   • Badge URLs, status page links, support links
3. Commit: git add <doc-files> && git commit -m "docs: update all documentation from Twilio to Telnyx"

Phase 4 exit: bash {baseDir}/scripts/migration-state.sh set-phase <project-root> 4 && bash {baseDir}/scripts/migration-state.sh set-commit <project-root> 4

If validation fails and you cannot fix the issue, document it and continue to the next product. Do not abandon the migration.