Skip to content

team-telnyx/ai / providers/claude/plugins/telnyx-platform/skills/telnyx-twilio-migration

telnyx-twilio-migration

Unverified

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.

FileKindSize
SKILL.mdskill md43.3 KB
references/account-setup-guide.mdmarkdown17.8 KB
references/error-code-mapping.mdmarkdown11.0 KB
references/fax-migration.mdmarkdown14.7 KB
references/iot-migration.mdmarkdown17.9 KB
references/lookup-migration.mdmarkdown14.3 KB
references/messaging-migration.mdmarkdown36.5 KB
references/mobile-sdk-migration.mdmarkdown38.6 KB
references/number-porting.mdmarkdown17.0 KB
references/numbers-migration.mdmarkdown21.1 KB
references/product-mapping.mdmarkdown6.7 KB
references/sdk-api-details/10dlc.mdmarkdown9.8 KB
references/sdk-api-details/ai-assistants.mdmarkdown5.8 KB
references/sdk-api-details/messaging.mdmarkdown16.1 KB
references/sdk-api-details/numbers.mdmarkdown10.1 KB
references/sdk-api-details/voice.mdmarkdown9.6 KB
references/sip-trunking-migration.mdmarkdown18.1 KB
references/texml-verbs.mdmarkdown43.7 KB
references/unsupported-products.mdmarkdown3.5 KB
references/verify-migration.mdmarkdown18.4 KB
references/video-migration.mdmarkdown20.6 KB
references/voice-migration.mdmarkdown37.2 KB
references/webhook-migration.mdmarkdown20.3 KB
references/webrtc-migration.mdmarkdown50.0 KB
scripts/lint-telnyx-correctness.shexecutablescript31.4 KB
scripts/migration-state.shexecutablescript7.3 KB
scripts/post-test-diagnostic.shexecutablescript18.9 KB
scripts/preflight-check.shexecutablescript13.4 KB
scripts/run-discovery.shexecutablescript7.7 KB
scripts/run-validation.shexecutablescript13.1 KB
scripts/scan-twilio-deep.pyexecutablescript64.8 KB
scripts/scan-twilio-usage.shexecutablescript29.1 KB
scripts/test-migration/smoke-test.shexecutablescript10.0 KB
scripts/test-migration/test-fax.shexecutablescript8.7 KB
scripts/test-migration/test-lookup.shexecutablescript5.5 KB
scripts/test-migration/test-messaging.shexecutablescript18.8 KB
scripts/test-migration/test-sip.shexecutablescript29.6 KB
scripts/test-migration/test-verify.shexecutablescript13.6 KB
scripts/test-migration/test-voice.shexecutablescript22.4 KB
scripts/test-migration/test-webhooks-local.pyexecutablescript9.7 KB
scripts/test-migration/test-webrtc.shexecutablescript24.0 KB
scripts/test-migration/webhook-receiver.pyexecutablescript11.8 KB
scripts/validate-migration.shexecutablescript31.1 KB
scripts/validate-texml.shexecutablescript61.4 KB
sdk-reference/curl/10dlc.mdmarkdown25.8 KB
sdk-reference/curl/account-access.mdmarkdown15.6 KB
sdk-reference/curl/account-management.mdmarkdown9.5 KB
sdk-reference/curl/account-notifications.mdmarkdown11.0 KB
sdk-reference/curl/account-reports.mdmarkdown45.5 KB
sdk-reference/curl/account.mdmarkdown8.1 KB
sdk-reference/curl/ai-assistants.mdmarkdown34.3 KB
sdk-reference/curl/ai-inference.mdmarkdown34.5 KB
sdk-reference/curl/fax.mdmarkdown19.8 KB
sdk-reference/curl/iot.mdmarkdown49.4 KB
sdk-reference/curl/messaging-hosted.mdmarkdown23.3 KB
sdk-reference/curl/messaging-profiles.mdmarkdown14.2 KB
sdk-reference/curl/messaging.mdmarkdown29.1 KB
sdk-reference/curl/missions.mdmarkdown23.5 KB
sdk-reference/curl/networking.mdmarkdown39.8 KB
sdk-reference/curl/numbers-compliance.mdmarkdown30.2 KB
sdk-reference/curl/numbers-config.mdmarkdown29.7 KB
sdk-reference/curl/numbers-services.mdmarkdown12.6 KB
sdk-reference/curl/numbers.mdmarkdown24.0 KB
sdk-reference/curl/oauth.mdmarkdown15.6 KB
sdk-reference/curl/porting-in.mdmarkdown35.1 KB
sdk-reference/curl/porting-out.mdmarkdown9.8 KB
sdk-reference/curl/sip-integrations.mdmarkdown27.5 KB
sdk-reference/curl/sip.mdmarkdown47.6 KB
sdk-reference/curl/storage.mdmarkdown4.2 KB
sdk-reference/curl/texml.mdmarkdown31.4 KB
sdk-reference/curl/verify.mdmarkdown13.2 KB
sdk-reference/curl/video.mdmarkdown17.2 KB
sdk-reference/curl/voice-advanced.mdmarkdown32.8 KB
sdk-reference/curl/voice-conferencing.mdmarkdown41.6 KB
sdk-reference/curl/voice-gather.mdmarkdown14.7 KB
sdk-reference/curl/voice-media.mdmarkdown17.8 KB
sdk-reference/curl/voice-streaming.mdmarkdown13.3 KB
sdk-reference/curl/voice.mdmarkdown37.6 KB
sdk-reference/curl/webrtc.mdmarkdown6.5 KB
sdk-reference/go/10dlc.mdmarkdown29.0 KB
sdk-reference/go/account-access.mdmarkdown17.0 KB
sdk-reference/go/account-management.mdmarkdown9.9 KB
sdk-reference/go/account-notifications.mdmarkdown12.4 KB
sdk-reference/go/account-reports.mdmarkdown31.5 KB
sdk-reference/go/account.mdmarkdown9.1 KB
sdk-reference/go/ai-assistants.mdmarkdown37.7 KB
sdk-reference/go/ai-inference.mdmarkdown27.1 KB
sdk-reference/go/fax.mdmarkdown20.2 KB
sdk-reference/go/iot.mdmarkdown51.3 KB
sdk-reference/go/messaging-hosted.mdmarkdown24.5 KB
sdk-reference/go/messaging-profiles.mdmarkdown15.2 KB
sdk-reference/go/messaging.mdmarkdown30.1 KB
sdk-reference/go/missions.mdmarkdown26.9 KB
sdk-reference/go/networking.mdmarkdown42.5 KB
sdk-reference/go/numbers-compliance.mdmarkdown28.2 KB
sdk-reference/go/numbers-config.mdmarkdown29.5 KB
sdk-reference/go/numbers-services.mdmarkdown14.1 KB
sdk-reference/go/numbers.mdmarkdown26.7 KB
sdk-reference/go/oauth.mdmarkdown11.7 KB
sdk-reference/go/porting-in.mdmarkdown41.1 KB
sdk-reference/go/porting-out.mdmarkdown10.9 KB
sdk-reference/go/sip-integrations.mdmarkdown32.3 KB
sdk-reference/go/sip.mdmarkdown49.1 KB
sdk-reference/go/storage.mdmarkdown4.8 KB
sdk-reference/go/texml.mdmarkdown35.7 KB
sdk-reference/go/verify.mdmarkdown14.4 KB
sdk-reference/go/video.mdmarkdown18.6 KB
sdk-reference/go/voice-advanced.mdmarkdown33.2 KB
sdk-reference/go/voice-conferencing.mdmarkdown42.3 KB
sdk-reference/go/voice-gather.mdmarkdown14.5 KB
sdk-reference/go/voice-media.mdmarkdown18.1 KB
sdk-reference/go/voice-streaming.mdmarkdown13.5 KB
sdk-reference/go/voice.mdmarkdown39.2 KB
sdk-reference/go/webrtc.mdmarkdown7.5 KB
sdk-reference/java/10dlc.mdmarkdown31.3 KB
sdk-reference/java/account-access.mdmarkdown18.5 KB
sdk-reference/java/account-management.mdmarkdown11.1 KB
sdk-reference/java/account-notifications.mdmarkdown14.3 KB
sdk-reference/java/account-reports.mdmarkdown36.5 KB
sdk-reference/java/account.mdmarkdown10.3 KB
sdk-reference/java/ai-assistants.mdmarkdown39.2 KB
sdk-reference/java/ai-inference.mdmarkdown30.7 KB
sdk-reference/java/fax.mdmarkdown21.5 KB
sdk-reference/java/iot.mdmarkdown57.5 KB
sdk-reference/java/messaging-hosted.mdmarkdown28.4 KB
sdk-reference/java/messaging-profiles.mdmarkdown15.7 KB
sdk-reference/java/messaging.mdmarkdown32.2 KB
sdk-reference/java/missions.mdmarkdown31.6 KB
sdk-reference/java/networking.mdmarkdown47.1 KB
sdk-reference/java/numbers-compliance.mdmarkdown31.1 KB
sdk-reference/java/numbers-config.mdmarkdown32.2 KB
sdk-reference/java/numbers-services.mdmarkdown15.9 KB
sdk-reference/java/numbers.mdmarkdown28.4 KB
sdk-reference/java/oauth.mdmarkdown13.0 KB
sdk-reference/java/porting-in.mdmarkdown46.2 KB
sdk-reference/java/porting-out.mdmarkdown11.9 KB
sdk-reference/java/sip-integrations.mdmarkdown38.1 KB
sdk-reference/java/sip.mdmarkdown51.9 KB
sdk-reference/java/storage.mdmarkdown5.7 KB
sdk-reference/java/texml.mdmarkdown41.3 KB
sdk-reference/java/verify.mdmarkdown16.0 KB
sdk-reference/java/video.mdmarkdown20.3 KB
sdk-reference/java/voice-advanced.mdmarkdown35.0 KB
sdk-reference/java/voice-conferencing.mdmarkdown46.0 KB
sdk-reference/java/voice-gather.mdmarkdown16.1 KB
sdk-reference/java/voice-media.mdmarkdown19.5 KB
sdk-reference/java/voice-streaming.mdmarkdown14.7 KB
sdk-reference/java/voice.mdmarkdown40.8 KB
sdk-reference/java/webrtc.mdmarkdown8.5 KB
sdk-reference/javascript/10dlc.mdmarkdown28.5 KB
sdk-reference/javascript/account-access.mdmarkdown15.9 KB
sdk-reference/javascript/account-management.mdmarkdown9.6 KB
sdk-reference/javascript/account-notifications.mdmarkdown11.7 KB
sdk-reference/javascript/account-reports.mdmarkdown29.3 KB
sdk-reference/javascript/account.mdmarkdown8.7 KB
sdk-reference/javascript/ai-assistants.mdmarkdown37.5 KB
sdk-reference/javascript/ai-inference.mdmarkdown24.4 KB
sdk-reference/javascript/fax.mdmarkdown19.9 KB
sdk-reference/javascript/iot.mdmarkdown47.4 KB
sdk-reference/javascript/messaging-hosted.mdmarkdown22.4 KB
sdk-reference/javascript/messaging-profiles.mdmarkdown14.8 KB
sdk-reference/javascript/messaging.mdmarkdown29.7 KB
sdk-reference/javascript/missions.mdmarkdown23.8 KB
sdk-reference/javascript/networking.mdmarkdown39.3 KB
sdk-reference/javascript/numbers-compliance.mdmarkdown25.9 KB
sdk-reference/javascript/numbers-config.mdmarkdown28.3 KB
sdk-reference/javascript/numbers-services.mdmarkdown13.0 KB
sdk-reference/javascript/numbers.mdmarkdown26.1 KB
sdk-reference/javascript/oauth.mdmarkdown10.8 KB
sdk-reference/javascript/porting-in.mdmarkdown37.4 KB
sdk-reference/javascript/porting-out.mdmarkdown10.2 KB
sdk-reference/javascript/sip-integrations.mdmarkdown28.5 KB
sdk-reference/javascript/sip.mdmarkdown47.4 KB
sdk-reference/javascript/storage.mdmarkdown4.5 KB
sdk-reference/javascript/texml.mdmarkdown31.9 KB
sdk-reference/javascript/verify.mdmarkdown13.3 KB
sdk-reference/javascript/video.mdmarkdown17.2 KB
sdk-reference/javascript/voice-advanced.mdmarkdown32.6 KB
sdk-reference/javascript/voice-conferencing.mdmarkdown40.4 KB
sdk-reference/javascript/voice-gather.mdmarkdown14.3 KB
sdk-reference/javascript/voice-media.mdmarkdown17.8 KB
sdk-reference/javascript/voice-streaming.mdmarkdown13.4 KB
sdk-reference/javascript/voice.mdmarkdown39.4 KB
sdk-reference/javascript/webrtc.mdmarkdown7.2 KB
sdk-reference/python/10dlc.mdmarkdown28.5 KB
sdk-reference/python/account-access.mdmarkdown15.0 KB
sdk-reference/python/account-management.mdmarkdown9.1 KB
sdk-reference/python/account-notifications.mdmarkdown10.9 KB
sdk-reference/python/account-reports.mdmarkdown28.1 KB
sdk-reference/python/account.mdmarkdown8.1 KB
sdk-reference/python/ai-assistants.mdmarkdown37.3 KB
sdk-reference/python/ai-inference.mdmarkdown23.4 KB
sdk-reference/python/fax.mdmarkdown19.5 KB
sdk-reference/python/iot.mdmarkdown45.3 KB
sdk-reference/python/messaging-hosted.mdmarkdown21.7 KB
sdk-reference/python/messaging-profiles.mdmarkdown14.1 KB
sdk-reference/python/messaging.mdmarkdown29.4 KB
sdk-reference/python/missions.mdmarkdown23.2 KB
sdk-reference/python/networking.mdmarkdown37.1 KB
sdk-reference/python/numbers-compliance.mdmarkdown24.6 KB

scripts/test-migration/test-webhooks-local.py

View on GitHub
#!/usr/bin/env python3
"""
test-webhooks-local.py -- Generate and send mock Telnyx webhook payloads

Sends mock webhook payloads to a local (or remote) endpoint for testing
that your webhook handler correctly parses Telnyx event formats.

NOTE: This tests payload FORMAT only, not cryptographic signature
validation. Signatures use a placeholder value since Ed25519 signing
requires external libraries (cryptography/nacl).

Usage:
    python3 test-webhooks-local.py [--url URL] [--event TYPE] [--delay SECS] [--help]

Arguments:
    --url URL         Webhook endpoint (default: http://localhost:8080/webhooks)
    --event TYPE      Send only this event type, or 'all' (default: all)
    --delay SECONDS   Delay between events in seconds (default: 0.5)
    --list            List available event types and exit
    --help            Show this help and exit

Requires: Python 3.8+ (stdlib only, no external dependencies)
"""

import argparse
import json
import sys
import time
import uuid
import urllib.request
import urllib.error
from datetime import datetime, timezone
from typing import Dict, Any, List, Optional, Tuple


# --- Mock Webhook Payloads ---

def _make_event(event_type: str, payload: Dict[str, Any]) -> Dict[str, Any]:
    """Wrap a payload in the standard Telnyx webhook event envelope."""
    return {
        "data": {
            "event_type": event_type,
            "id": str(uuid.uuid4()),
            "occurred_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00",
            "payload": payload,
            "record_type": "event",
        },
        "meta": {
            "attempt": 1,
            "delivered_to": "http://localhost:8080/webhooks",
        },
    }


def _call_control_payload(state: str, direction: str = "incoming") -> Dict[str, Any]:
    return {
        "call_control_id": str(uuid.uuid4()),
        "call_leg_id": str(uuid.uuid4()),
        "call_session_id": str(uuid.uuid4()),
        "connection_id": "1234567890",
        "client_state": None,
        "from": "+15551234567",
        "to": "+15559876543",
        "direction": direction,
        "state": state,
        "record_type": "call",
    }


MOCK_EVENTS: Dict[str, callable] = {
    "call.initiated": lambda: _make_event("call.initiated", _call_control_payload("initiated")),

    "call.answered": lambda: _make_event("call.answered", _call_control_payload("answered")),

    "call.hangup": lambda: _make_event("call.hangup", {
        **_call_control_payload("hangup"),
        "hangup_cause": "normal_clearing",
        "hangup_source": "caller",
        "sip_hangup_cause": "200",
    }),

    "message.received": lambda: _make_event("message.received", {
        "id": str(uuid.uuid4()),
        "record_type": "message",
        "direction": "inbound",
        "type": "SMS",
        "from": {"phone_number": "+15551234567", "carrier": "T-Mobile", "line_type": "wireless"},
        "to": [{"phone_number": "+15559876543", "status": "delivered"}],
        "text": "Hello from test-webhooks-local!",
        "messaging_profile_id": str(uuid.uuid4()),
        "encoding": "GSM-7",
        "parts": 1,
        "cost": {"amount": "0.0040", "currency": "USD"},
    }),

    "message.sent": lambda: _make_event("message.sent", {
        "id": str(uuid.uuid4()),
        "record_type": "message",
        "direction": "outbound",
        "type": "SMS",
        "from": {"phone_number": "+15559876543"},
        "to": [{"phone_number": "+15551234567", "status": "sent"}],
        "text": "Reply from Telnyx!",
        "messaging_profile_id": str(uuid.uuid4()),
        "parts": 1,
        "cost": {"amount": "0.0040", "currency": "USD"},
    }),

    "message.finalized": lambda: _make_event("message.finalized", {
        "id": str(uuid.uuid4()),
        "record_type": "message",
        "direction": "outbound",
        "type": "SMS",
        "from": {"phone_number": "+15559876543"},
        "to": [{"phone_number": "+15551234567", "status": "delivered"}],
        "text": "Reply from Telnyx!",
        "completed_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00",
        "parts": 1,
        "cost": {"amount": "0.0040", "currency": "USD"},
    }),

    "verify.verification": lambda: _make_event("verify.verification", {
        "id": str(uuid.uuid4()),
        "record_type": "verification",
        "phone_number": "+15551234567",
        "verify_profile_id": str(uuid.uuid4()),
        "status": "accepted",
        "type": "sms",
        "timeout_secs": 300,
        "created_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00",
        "updated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "+00:00",
    }),

    "fax.received": lambda: _make_event("fax.received", {
        "id": str(uuid.uuid4()),
        "record_type": "fax",
        "connection_id": "1234567890",
        "direction": "inbound",
        "from": "+15551234567",
        "to": "+15559876543",
        "status": "received",
        "media_url": "https://api.telnyx.com/v2/faxes/test/media",
        "quality": "normal",
        "page_count": 2,
    }),

    "fax.failed": lambda: _make_event("fax.failed", {
        "id": str(uuid.uuid4()),
        "record_type": "fax",
        "connection_id": "1234567890",
        "direction": "outbound",
        "from": "+15559876543",
        "to": "+15551234567",
        "status": "failed",
        "failure_reason": "destination_busy",
    }),
}

# Placeholder signature header (Ed25519 requires external libraries)
PLACEHOLDER_SIGNATURE = "dGVzdC1zaWduYXR1cmUtcGxhY2Vob2xkZXI="
PLACEHOLDER_TIMESTAMP = str(int(time.time()))


def send_webhook(url: str, event: Dict[str, Any]) -> Tuple[int, str, float]:
    """Send a single webhook payload. Returns (status_code, body, elapsed_ms)."""
    body = json.dumps(event).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=body,
        method="POST",
        headers={
            "Content-Type": "application/json",
            "telnyx-signature-ed25519": PLACEHOLDER_SIGNATURE,
            "telnyx-timestamp": PLACEHOLDER_TIMESTAMP,
            "User-Agent": "telnyx-test-webhooks/1.0",
        },
    )

    start = time.monotonic()
    try:
        with urllib.request.urlopen(req, timeout=10) as resp:
            elapsed = (time.monotonic() - start) * 1000
            resp_body = resp.read().decode("utf-8", errors="replace")
            return resp.status, resp_body, elapsed
    except urllib.error.HTTPError as e:
        elapsed = (time.monotonic() - start) * 1000
        resp_body = e.read().decode("utf-8", errors="replace") if e.fp else ""
        return e.code, resp_body, elapsed
    except urllib.error.URLError as e:
        elapsed = (time.monotonic() - start) * 1000
        return 0, str(e.reason), elapsed
    except Exception as e:
        elapsed = (time.monotonic() - start) * 1000
        return 0, str(e), elapsed


def truncate(text: str, max_len: int = 200) -> str:
    if len(text) <= max_len:
        return text
    return text[:max_len] + "... (truncated)"


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Send mock Telnyx webhook payloads for local testing",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "NOTE: Signatures are placeholders. This tests payload FORMAT, not crypto.\n\n"
            "Available event types:\n  " + "\n  ".join(sorted(MOCK_EVENTS.keys()))
        ),
    )
    parser.add_argument(
        "--url", default="http://localhost:8080/webhooks",
        help="Webhook endpoint URL (default: http://localhost:8080/webhooks)",
    )
    parser.add_argument(
        "--event", default="all",
        help="Event type to send, or 'all' (default: all)",
    )
    parser.add_argument(
        "--delay", type=float, default=0.5,
        help="Delay in seconds between events (default: 0.5)",
    )
    parser.add_argument(
        "--list", action="store_true",
        help="List available event types and exit",
    )
    args = parser.parse_args()

    if args.list:
        print("Available event types:")
        for name in sorted(MOCK_EVENTS.keys()):
            print(f"  {name}")
        return 0

    # Determine which events to send
    if args.event == "all":
        event_names = list(MOCK_EVENTS.keys())
    elif args.event in MOCK_EVENTS:
        event_names = [args.event]
    else:
        print(f"Error: unknown event type '{args.event}'", file=sys.stderr)
        print(f"Available types: {', '.join(sorted(MOCK_EVENTS.keys()))}", file=sys.stderr)
        return 1

    print(f"Telnyx Webhook Test")
    print(f"===================")
    print(f"Target URL:  {args.url}")
    print(f"Events:      {len(event_names)}")
    print(f"Delay:       {args.delay}s")
    print(f"")
    print(f"NOTE: Signatures are placeholders — this tests payload format, not crypto.")
    print(f"")

    passed = 0
    failed = 0

    for i, name in enumerate(event_names):
        event = MOCK_EVENTS[name]()
        status, body, elapsed = send_webhook(args.url, event)

        if status >= 200 and status < 300:
            result = "PASS"
            passed += 1
        elif status == 0:
            result = "FAIL"
            failed += 1
        else:
            result = "WARN"
            failed += 1

        print(f"  [{result}] {name}")
        print(f"         Status: {status if status > 0 else 'connection error'} | {elapsed:.0f}ms")
        if body:
            print(f"         Body:   {truncate(body.strip())}")

        # Delay between events (but not after the last one)
        if i < len(event_names) - 1 and args.delay > 0:
            time.sleep(args.delay)

    print(f"")
    print(f"===================")
    print(f"Results: {passed} passed, {failed} failed out of {len(event_names)}")

    return 0 if failed == 0 else 1


if __name__ == "__main__":
    sys.exit(main())
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall