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

references/account-setup-guide.md

View on GitHub
# Telnyx Account Setup Guide

Prerequisites and automated API setup for migrating from Twilio to Telnyx.

## What You Must Do Manually (Portal)

These steps **cannot** be automated via API — the user must complete them at [portal.telnyx.com](https://portal.telnyx.com):

1. **Create a Telnyx account** — Sign up at https://telnyx.com/sign-up
2. **Complete any required account-level/KYC verification** — Requirements vary by account, product, and destination; an API key can be created before every product is enabled
3. **Add payment method** — Credit card or ACH required for purchases
4. **Accept Terms of Service** — Must be accepted in the portal
5. **Generate API Key v2** — https://portal.telnyx.com/#/app/api-keys
6. **Note your Public Key** — https://portal.telnyx.com/#/app/account/public-key (for webhook signature validation)

## What Can Be Automated (API)

Once the user has an API key, API-manageable resources can be created based on scan results after the applicable approval gate. `--dry-run` is read-only. A confirmed run may create a dedicated run-owned resource, but it must not change existing routing, assignments, destination allowlists, or push credentials without a separate explicit opt-in that identifies the target resource.

### Messaging Profile (sender-dependent)

```bash
curl -X POST https://api.telnyx.com/v2/messaging_profiles \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Migration - Messaging Profile",
    "whitelisted_destinations": ["US"],
    "webhook_url": "https://example.com/webhooks/messaging",
    "webhook_failover_url": "https://example.com/webhooks/messaging-backup"
  }'
```

Replace `US` with every ISO 3166-1 alpha-2 destination the migration will send to. Use `["*"]` only after an explicit decision to allow every destination. Both `name` and `whitelisted_destinations` are required when creating a Messaging Profile. The `messaging_profile_id` send parameter is required for number-pool and alphanumeric-sender requests; a Telnyx phone number or short code can resolve its assigned profile without that body field.

Save the returned `id` as `TELNYX_MESSAGING_PROFILE_ID`.

### Voice Connection (required for voice/TeXML)

**TeXML Application:**
```bash
curl -X POST https://api.telnyx.com/v2/texml_applications \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "Migration - TeXML App",
    "voice_url": "https://example.com/voice",
    "voice_method": "POST",
    "status_callback": "https://example.com/status",
    "status_callback_method": "POST"
  }'
```

**Call Control Application:**
```bash
curl -X POST https://api.telnyx.com/v2/call_control_applications \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_name": "Migration - Call Control App",
    "webhook_event_url": "https://example.com/webhooks/voice",
    "webhook_event_failover_url": "https://example.com/webhooks/voice-backup",
    "webhook_api_version": "2"
  }'
```

### Outbound Voice Profile (required for outbound calls)

```bash
curl -X POST https://api.telnyx.com/v2/outbound_voice_profiles \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Migration - Outbound Profile",
    "traffic_type": "conversational",
    "enabled": true,
    "whitelisted_destinations": ["US"]
  }'
```

Replace `US` with every ISO 3166-1 alpha-2 destination the migration will call. If an existing OVP needs an allowlist change, obtain explicit approval first and include its current `name` in `PATCH /v2/outbound_voice_profiles/{id}`; the update schema requires `name`.

Save the returned OVP `id`. Before using it for outbound voice or fax, verify that the profile is `enabled: true` and that `whitelisted_destinations` contains the destination ISO-2 code (or the deliberately approved wildcard `*`).

### Phone Number Purchase (requires user approval — costs money)

```bash
# Search for available numbers
curl -X GET -G --data-urlencode "filter[country_code]=US" \
     --data-urlencode "filter[features][]=sms" \
     --data-urlencode "filter[features][]=voice" \
  "https://api.telnyx.com/v2/available_phone_numbers" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

# Purchase (REQUIRES USER APPROVAL before executing)
curl -X POST https://api.telnyx.com/v2/number_orders \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [{"phone_number": "+15551234567"}],
    "connection_id": "YOUR_CONNECTION_ID",
    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
  }'
```

### Number Assignment to Connection/Profile

```bash
# Resolve the API resource ID; update endpoints do not use the E.164 number as {id}.
REQUESTED_NUMBER="+15551234567"
if ! PHONE_NUMBER_ID="$(
  curl -fsS -G "https://api.telnyx.com/v2/phone_numbers" \
    -H "Authorization: Bearer $TELNYX_API_KEY" \
    --data-urlencode "filter[phone_number]=$REQUESTED_NUMBER" \
    --data-urlencode "page[size]=1" |
    jq -er --arg number "$REQUESTED_NUMBER" \
      '[.data[] | select(.phone_number == $number)] | .[0].id'
)"; then
  echo "Exact phone number not found" >&2
  exit 1
fi

# Inspect both current assignments, then bind approval to the exact transition.
CURRENT_NUMBER=$(curl -fsS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID") || exit 1
CURRENT_MESSAGING=$(curl -fsS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID/messaging") || exit 1
CURRENT_CONNECTION_ID=$(jq -er '.data.connection_id // "unassigned"' \
  <<<"$CURRENT_NUMBER") || exit 1
CURRENT_PROFILE_ID=$(jq -er '.data.messaging_profile_id // "unassigned"' \
  <<<"$CURRENT_MESSAGING") || exit 1
CURRENT_CONNECTION_JSON=$(jq -c '.data.connection_id // null' \
  <<<"$CURRENT_NUMBER") || exit 1
NEW_CONNECTION_ID="YOUR_CONNECTION_ID"
NEW_PROFILE_ID="YOUR_MESSAGING_PROFILE_ID"
# Preflight both target resources before changing either live assignment.
curl -fsS -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/connections/$NEW_CONNECTION_ID" \
  | jq -e --arg id "$NEW_CONNECTION_ID" '.data.id == $id' >/dev/null || exit 1
curl -fsS -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/messaging_profiles/$NEW_PROFILE_ID" \
  | jq -e --arg id "$NEW_PROFILE_ID" '.data.id == $id' >/dev/null || exit 1
ASSIGNMENT_APPROVAL="$PHONE_NUMBER_ID|$REQUESTED_NUMBER|voice:$CURRENT_CONNECTION_ID->$NEW_CONNECTION_ID|messaging:$CURRENT_PROFILE_ID->$NEW_PROFILE_ID"
printf 'Assignment approval token: %s\n' "$ASSIGNMENT_APPROVAL"
test "${TELNYX_APPROVE_NUMBER_ASSIGNMENT:-}" = "$ASSIGNMENT_APPROVAL" || {
  echo "Number rerouting not approved" >&2; exit 1;
}

# Assign the reviewed number to the reviewed voice connection.
curl -fsS -X PATCH "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -cn --arg id "$NEW_CONNECTION_ID" '{connection_id: $id}')" || exit 1

# Assign the same reviewed number to the reviewed messaging profile. Restore
# the previous voice assignment if this second mutation fails.
if ! curl -fsS -X PATCH "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID/messaging" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -cn --arg id "$NEW_PROFILE_ID" '{messaging_profile_id: $id}')"; then
  echo "Messaging assignment failed; restoring previous voice assignment" >&2
  curl -fsS -X PATCH "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID" \
    -H "Authorization: Bearer $TELNYX_API_KEY" \
    -H "Content-Type: application/json" \
    --data "$(jq -cn --argjson id "$CURRENT_CONNECTION_JSON" '{connection_id: $id}')" || {
      echo "CRITICAL: voice rollback failed; inspect the number immediately" >&2;
    }
  exit 1
fi

# Read both resources back. A successful PATCH response alone does not prove
# that the requested routing state is active.
FINAL_NUMBER=$(curl -fsS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID") || exit 1
FINAL_MESSAGING=$(curl -fsS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers/$PHONE_NUMBER_ID/messaging") || exit 1
jq -e --arg id "$NEW_CONNECTION_ID" '.data.connection_id == $id' \
  <<<"$FINAL_NUMBER" >/dev/null || exit 1
jq -e --arg id "$NEW_PROFILE_ID" '.data.messaging_profile_id == $id' \
  <<<"$FINAL_MESSAGING" >/dev/null || exit 1
```

### Verify Profile (required for verify/2FA)

```bash
curl -X POST https://api.telnyx.com/v2/verify_profiles \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Migration - Verify Profile",
    "sms": {
      "whitelisted_destinations": ["US"],
      "default_verification_timeout_secs": 300,
      "code_length": 6
    }
  }'
```

Replace `US` with every ISO 3166-1 alpha-2 destination that will receive SMS verifications. The current Verify Profile API nests channel settings under `sms`; `messaging_enabled` and a top-level `default_timeout_secs` are not fields in the create schema.

### Fax Application (required for fax)

Outbound fax requires all three relationships to agree: an active Fax Application, an enabled OVP attached at `outbound.outbound_voice_profile_id`, and the exact sender phone number assigned to that Fax Application through the phone number's `connection_id`. Creating the application alone is not sufficient.

```bash
# Create the Fax Application with the active, destination-authorized OVP from above.
curl -X POST https://api.telnyx.com/v2/fax_applications \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "application_name": "Migration - Fax App",
    "webhook_event_url": "https://example.com/webhooks/fax",
    "active": true,
    "outbound": {
      "outbound_voice_profile_id": "YOUR_OUTBOUND_VOICE_PROFILE_ID"
    }
  }'

# Resolve the exact owned sender number to its resource ID.
FAX_FROM_NUMBER="+15551234567"
FAX_PHONE_NUMBER_ID="$(
  curl -fsS -G "https://api.telnyx.com/v2/phone_numbers" \
    -H "Authorization: Bearer $TELNYX_API_KEY" \
    --data-urlencode "filter[phone_number]=$FAX_FROM_NUMBER" \
    --data-urlencode "page[size]=1" |
    jq -er --arg number "$FAX_FROM_NUMBER" \
      '[.data[] | select(.phone_number == $number and .status == "active")] | .[0].id'
)"

# Inspect the current assignment and bind approval to the exact reroute.
CURRENT_FAX_NUMBER=$(curl -fsS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/phone_numbers/$FAX_PHONE_NUMBER_ID") || exit 1
CURRENT_FAX_CONNECTION_ID=$(jq -er '.data.connection_id // "unassigned"' \
  <<<"$CURRENT_FAX_NUMBER") || exit 1
NEW_FAX_APPLICATION_ID="YOUR_FAX_APPLICATION_ID"
FAX_ASSIGNMENT_APPROVAL="$FAX_PHONE_NUMBER_ID|$FAX_FROM_NUMBER|fax:$CURRENT_FAX_CONNECTION_ID->$NEW_FAX_APPLICATION_ID"
printf 'Fax reroute approval token: %s\n' "$FAX_ASSIGNMENT_APPROVAL"
test "${TELNYX_APPROVE_FAX_REROUTE:-}" = "$FAX_ASSIGNMENT_APPROVAL" || {
  echo "Fax-number reroute not approved" >&2; exit 1;
}
curl -fsS -X PATCH "https://api.telnyx.com/v2/phone_numbers/$FAX_PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -cn --arg id "$NEW_FAX_APPLICATION_ID" '{connection_id: $id}')"
```

The owned-number response does not include the available-inventory `features` array. Fax readiness is established by the exact active-number assignment and the Fax Application/OVP checks below.

Before a dry run or send, retrieve the number, Fax Application, and OVP and verify the exact chain: number `connection_id` equals the intended Fax Application ID; the application is active; `outbound.outbound_voice_profile_id` equals the intended OVP ID; and that OVP is enabled and allows the destination's ISO-2 code. `scripts/test-migration/test-fax.sh` enforces this chain and refuses a mismatched `TELNYX_CONNECTION_ID`.

### 10DLC Registration (required for US A2P messaging)

10DLC registration can be completed through the Mission Control Portal or API. Treat brand and campaign submission as production compliance actions, not smoke-test setup:

1. **Prepare the compliance record** — collect the legal business identity, use case, opt-in/message flow, sample messages, help/stop behavior, privacy policy, terms, and any required reseller or age-gating details. Do not invent these fields.
2. **Quote and approve brand registration** — check current authoritative pricing and obtain explicit approval for the current non-refundable brand-registration charge. Then submit the brand with `POST /v2/10dlc/brand`. Brand creation is billable even if verification later fails; validate the legal name/EIN and other identity fields before submission.
3. **Wait for a usable brand status** — retrieve the brand and resolve any verification or vetting failures before building a campaign. External vetting may be a separate billable action and requires its own current quote and approval.
4. **Qualify before submission** — call the read-only `GET /v2/10dlc/campaignBuilder/brand/{brandId}/usecase/{usecase}` endpoint. Do not submit if the brand is not qualified. Use the returned fee fields together with current pricing to present the campaign charge and obtain explicit approval.
5. **Submit exactly once** — after approval, submit the complete campaign with `POST /v2/10dlc/campaignBuilder`. Campaign creation incurs an upfront, non-refundable charge covering the first three months, based on use case. Most campaign fields become immutable after creation, so re-check consent text, sample messages, links, and use case before submitting; a failed or duplicate submission can still create cost or compliance work.
6. **Wait for carrier/Telnyx acceptance, then assign numbers** — do not send A2P traffic or attach numbers while the campaign is pending or failed. After approval, ensure each long-code number is already on the intended Messaging Profile, assign it through the current Phone Number Campaigns API, and verify the assignment status before sending.

The `--confirm` gates used by integration-test scripts do not authorize either 10DLC brand creation or campaign submission. Record the exact user-approved action, current amount/currency, brand/use case, and maximum charge before each billable registration call.

> See `{baseDir}/sdk-reference/{lang}/10dlc.md` for complete API examples.

### Webhook Configuration

After creating resources, configure webhook URLs to point to your application server. If migrating incrementally, you can use the same URLs as your Twilio webhooks (the handler code will be updated in Phase 4).

## Approval Gates

The agent MUST get user approval before:

- **Purchasing phone numbers** — costs money
- **Creating 10DLC campaigns** — costs money and involves compliance
- **Creating 10DLC brands or requesting external vetting** — costs may be non-refundable even if verification fails
- **Porting numbers from Twilio** — irreversible once completed
- **Setting up production webhook URLs** — affects live traffic
- **Expanding an existing Messaging Profile, OVP, or Verify Profile destination allowlist** — changes live send/call permissions
- **Reassigning a phone number to another Messaging Profile or voice connection** — changes live routing
- **Attaching or replacing an OVP or mobile push credential on an existing connection** — changes live call or push behavior

## What's Needed Per Product

| Detected Product | Resources to Create |
|---|---|
| messaging | Messaging Profile for number-pool/alphanumeric sends or number routing; sender phone number(s)/short code as applicable |
| voice / texml | TeXML App OR Call Control App, Outbound Voice Profile, phone number(s) |
| verify | Verify Profile |
| fax | Active Fax Application, active destination-authorized Outbound Voice Profile, fax-capable phone number(s) assigned to that application |
| sip / sip-integrations | SIP Connection (IP/Credential/FQDN), Outbound Voice Profile |
| webrtc | Credential Connection and Telephony Credential(s); for native mobile push, platform Mobile Push Credential(s) attached to the connection |
| iot | SIM Card Group(s) |
| 10dlc | Brand registration, campaign(s) |

## New Account (No Numbers or Resources)

For a brand new Telnyx account with no phone numbers:

1. Provide the destination's ISO 3166-1 alpha-2 code as `TELNYX_TO_COUNTRY`. If it is unavailable, the user can separately opt into a billed Telnyx Number Lookup with `TELNYX_ALLOW_COUNTRY_LOOKUP=yes`; scripts do not guess from ambiguous calling-code prefixes or perform a paid lookup implicitly.
2. Test scripts may show a current inventory quote but never purchase a persistent phone number. Complete purchase as a separate approval workflow after re-querying the authoritative upfront and recurring cost.
3. A confirmed run may create dedicated run-owned profiles or connections. Assigning an already-owned number still follows the existing-resource consent policy.

`TELNYX_API_KEY` and `TELNYX_TO_NUMBER` are common inputs, not a guarantee that every account can run end-to-end immediately. Account level, payment, inventory, destination approval, 10DLC/toll-free registration, and country-specific regulatory requirements may require additional setup.

## Existing Telnyx Users

If the user already has a Telnyx account, the preflight check (`scripts/preflight-check.sh`) and test scripts can discover:

- Existing Messaging Profiles
- Existing voice connections
- Existing phone numbers and their current assignments
- Account balance

Discovery does not authorize mutation. Reuse an existing resource only after identifying it and confirming it already matches the migration. If a change would affect live routing, a destination allowlist, a profile or OVP assignment, or push credentials, fail with remediation or require an explicit opt-in that identifies the exact resource.
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