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/verify-migration.md

View on GitHub
# Verify Migration: Twilio Verify to Telnyx Verify

Migrate from Twilio Verify to the Telnyx Verify API for phone number verification and 2FA.

> **CRITICAL: `verify_profile_id` is REQUIRED on every Telnyx Verify API call.** Unlike Twilio where the Service SID is in the URL path, Telnyx requires `verify_profile_id` as a body parameter on both send and check requests. Omitting it will cause a 422 error. Create a profile first (see Setup below), then include it in every request.

## Table of Contents

- [Overview](#overview)
- [Verification Methods](#verification-methods)
- [Setup](#setup)
- [Sending Verification Codes](#sending-verification-codes)
- [Checking Verification Codes](#checking-verification-codes)
- [Flash Calling](#flash-calling)
- [Concept Mapping](#concept-mapping)
- [Webhook Differences](#webhook-differences)

## Overview

Telnyx Verify is not a drop-in replacement for Twilio Verify. The API surface is different, but the functionality is equivalent. Key differences:

- Telnyx uses a **Verify Profile** (analogous to Twilio's Verify Service)
- Different endpoint structure and parameter names
- Telnyx supports flash calling (missed-call verification) which Twilio does not offer on Verify
- Both platforms support WhatsApp verification; Telnyx selects it with the `/verifications/whatsapp` endpoint

## Verification Methods

| Method | Twilio Verify | Telnyx Verify |
|---|---|---|
| SMS OTP | Yes | Yes |
| Voice call OTP | Yes | Yes (`call` channel) |
| WhatsApp OTP | Yes (`whatsapp` channel) | Yes (`/verifications/whatsapp`) |
| Email OTP | Yes | No |
| Push notification | Yes (Authy) | No |
| TOTP | Yes (Authy) | No |
| Flash calling | No | Yes — verification via missed call (caller ID matching) |
| Custom SMS templates | Yes — `TemplateSid` / service `DefaultTemplateSid` | Yes — templates attached to a Verify Profile with `sms.messaging_template_id` |

## Setup

### Create a Verify Profile

Configure every channel this migration will trigger. This profile is ready for
SMS, voice call, and flash-call verification to US destinations; replace `US`
with the actual ISO 3166-1 alpha-2 destinations before creating it.

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

Note the `id` in the response — this is your Verify Profile ID.

### Twilio Setup (for comparison)

```javascript
// Twilio: create Verify Service
const service = await client.verify.v2.services.create({
  friendlyName: 'My App Verification'
});
// service.sid = 'VA...'
```

## Sending Verification Codes

### SMS Verification

```python
# Twilio
verification = client.verify.v2 \
    .services('VA...') \
    .verifications \
    .create(to='+15559876543', channel='sms')

# Telnyx
from telnyx import Telnyx
client = Telnyx(api_key="YOUR_API_KEY")
verification = client.verifications.trigger_sms(
    phone_number="+15559876543",
    verify_profile_id="YOUR_PROFILE_ID"
)
```

```javascript
// Twilio
const verification = await client.verify.v2
  .services('VA...')
  .verifications
  .create({ to: '+15559876543', channel: 'sms' });

// Telnyx
const Telnyx = require('telnyx');
const client = new Telnyx({ apiKey: 'YOUR_API_KEY' });
const verification = await client.verifications.triggerSMS({
  phone_number: '+15559876543',
  verify_profile_id: 'YOUR_PROFILE_ID'
});
```

```bash
# Twilio
curl -X POST "https://verify.twilio.com/v2/Services/$SERVICE_SID/Verifications" \
  -u "$SID:$AUTH_TOKEN" \
  -d "To=+15559876543" -d "Channel=sms"

# Telnyx
curl -X POST https://api.telnyx.com/v2/verifications/sms \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15559876543",
    "verify_profile_id": "YOUR_PROFILE_ID"
  }'
```

```go
// Go — Twilio
import "github.com/twilio/twilio-go"
import verify "github.com/twilio/twilio-go/rest/verify/v2"

client := twilio.NewRestClient()
params := &verify.CreateVerificationParams{}
params.SetTo("+15559876543")
params.SetChannel("sms")
resp, _ := client.VerifyV2.CreateVerification("VA...", params)

// Go — Telnyx (REST API)
// POST https://api.telnyx.com/v2/verifications/sms
// {"phone_number":"+15559876543","verify_profile_id":"..."}
```

```ruby
# Twilio
verification = client.verify.v2
  .services('VA...')
  .verifications
  .create(to: '+15559876543', channel: 'sms')

# Telnyx
client = Telnyx::Client.new(api_key: 'YOUR_API_KEY')
verification = client.verifications.trigger_sms(
  phone_number: '+15559876543',
  verify_profile_id: 'YOUR_PROFILE_ID'
)
```

```java
// Twilio
import com.twilio.rest.verify.v2.service.Verification;

Verification verification = Verification.creator("VA...", "+15559876543", "sms").create();

// Telnyx — use REST API
// POST https://api.telnyx.com/v2/verifications/sms with JSON body
// {"phone_number":"+15559876543","verify_profile_id":"..."}
```

### Voice Call Verification

```python
# Twilio
verification = client.verify.v2 \
    .services('VA...') \
    .verifications \
    .create(to='+15559876543', channel='call')

# Telnyx
verification = client.verifications.trigger_call(
    phone_number="+15559876543",
    verify_profile_id="YOUR_PROFILE_ID"
)
```

### WhatsApp Verification

Twilio's `channel='whatsapp'` maps to Telnyx's WhatsApp-specific endpoint. Configure the profile's `whatsapp` settings (including the WABA, sender phone number, template, and allowed destinations) before triggering it.

For a profile created in the setup step, explicitly approve updating that
named profile, then attach its WhatsApp channel settings:

```bash
WHATSAPP_COUNTRY="US"
WHATSAPP_WABA_ID="YOUR_WABA_ID"
WHATSAPP_SENDER="+13035551234"
WHATSAPP_TEMPLATE="YOUR_AUTHENTICATION_TEMPLATE_NAME"
WHATSAPP_APPROVAL="$TELNYX_VERIFY_PROFILE_ID|countries:$WHATSAPP_COUNTRY|waba:$WHATSAPP_WABA_ID|sender:$WHATSAPP_SENDER|template:$WHATSAPP_TEMPLATE"
printf 'Verify profile update approval token: %s\n' "$WHATSAPP_APPROVAL"
test "${TELNYX_APPROVE_VERIFY_PROFILE_UPDATE:-}" = "$WHATSAPP_APPROVAL" || {
  echo "Verify profile WhatsApp update not approved" >&2; exit 1;
}

curl -fsS -X PATCH "https://api.telnyx.com/v2/verify_profiles/$TELNYX_VERIFY_PROFILE_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -cn \
    --arg country "$WHATSAPP_COUNTRY" \
    --arg waba "$WHATSAPP_WABA_ID" \
    --arg sender "$WHATSAPP_SENDER" \
    --arg template "$WHATSAPP_TEMPLATE" \
    '{"whatsapp": {whitelisted_destinations:[$country],default_verification_timeout_secs:300,waba_id:$waba,sender_phone_number:$sender,template_id:$template}}')" || exit 1
```

Replace `US`, the WABA ID, sender, and template with the resources approved for
this migration. Do not patch an unrelated or pre-existing profile implicitly.

```bash
# Twilio
curl -X POST "https://verify.twilio.com/v2/Services/$SERVICE_SID/Verifications" \
  -u "$SID:$AUTH_TOKEN" \
  -d "To=+15559876543" -d "Channel=whatsapp"

# Telnyx
curl -X POST https://api.telnyx.com/v2/verifications/whatsapp \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15559876543",
    "verify_profile_id": "YOUR_PROFILE_ID"
  }'
```

### Parameter Mapping

| Twilio | Telnyx | Notes |
|---|---|---|
| `to` | `phone_number` | E.164 format |
| `channel` | endpoint (`/verifications/sms`, `/verifications/call`, `/verifications/flashcall`, `/verifications/whatsapp`) | Channel is chosen by the endpoint, not a body param; the `type` field is response-only |
| Service SID (`VA...`) | `verify_profile_id` | Profile ID from setup |
| `TemplateSid` / service `DefaultTemplateSid` | Profile `sms.messaging_template_id` | Telnyx template selection is profile-scoped, not a trigger parameter |
| `locale` | Not specified | Language determined by phone number region |
| `customCode` | `custom_code` | Use your own code (optional) |

## Checking Verification Codes

```python
# Twilio
check = client.verify.v2 \
    .services('VA...') \
    .verification_checks \
    .create(to='+15559876543', code='123456')
# check.status == 'approved' or 'pending'

# Telnyx
result = client.verifications.by_phone_number.actions.verify(
    phone_number="+15559876543",
    code="123456",
    verify_profile_id="YOUR_PROFILE_ID"
)
# result.response_code == 'accepted' or 'rejected'
```

```javascript
// Twilio
const check = await client.verify.v2
  .services('VA...')
  .verificationChecks
  .create({ to: '+15559876543', code: '123456' });
// check.status === 'approved'

// Telnyx
const result = await client.verifications.byPhoneNumber.actions.verify(
  '+15559876543',
  { code: '123456', verify_profile_id: 'YOUR_PROFILE_ID' }
);
// result.data.response_code === 'accepted'
```

```bash
# Twilio
curl -X POST "https://verify.twilio.com/v2/Services/$SERVICE_SID/VerificationChecks" \
  -u "$SID:$AUTH_TOKEN" \
  -d "To=+15559876543" -d "Code=123456"

# Telnyx
curl -X POST "https://api.telnyx.com/v2/verifications/by_phone_number/+15559876543/actions/verify" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456", "verify_profile_id": "YOUR_PROFILE_ID"}'
```

### Status Mapping

The verify **action** (`.../actions/verify`) returns a `response_code` that is only ever `accepted` or `rejected`. This is distinct from a verification's `status` field, whose enum is `pending`, `accepted`, `invalid`, `expired`, `error`.

| Twilio Status | Telnyx verify-action `response_code` | Meaning |
|---|---|---|
| `approved` | `accepted` | Code is correct |
| `pending` | `rejected` | Submitted code is incorrect or expired |
| `canceled` | N/A | No equivalent action response |

Note: a freshly created verification has `status: "pending"` (still awaiting a code). Do not confuse the create-time `status` (`pending`) with the verify-action `response_code` (`rejected`).

## Flash Calling

Telnyx-only feature. Verification via a missed call — the user's phone displays a caller ID, and the last N digits of that number are the verification code. No SMS charges, faster in some markets.

```python
verification = client.verifications.trigger_flashcall(
    phone_number="+15559876543",
    verify_profile_id="YOUR_PROFILE_ID"
)
```

The user sees an incoming call that auto-disconnects. Your app reads the caller ID and extracts the code automatically (or prompts the user to enter it).

**Flash Call Configuration on Verify Profile:**

The current profile-create schema accepts `flashcall`, but the profile-update schema does not. Configure flash calling when creating the profile rather than sending a `flashcall` field to `PATCH /verify_profiles/{id}`:

```bash
curl -X POST https://api.telnyx.com/v2/verify_profiles \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App Verification",
    "flashcall": {
      "app_name": "My App",
      "whitelisted_destinations": ["US"],
      "default_verification_timeout_secs": 300
    }
  }'
```

Replace `US` with the actual ISO 3166-1 alpha-2 destinations before creating
the profile.

**How it works:**
1. Your app calls `POST /v2/verifications/flashcall` with `phone_number` and `verify_profile_id`
2. Telnyx places a call to the user's phone that auto-disconnects after 1 ring
3. The caller ID of that call contains the verification digits
4. Your mobile app detects the incoming call's caller ID and extracts the code automatically
5. Call `POST /v2/verifications/by_phone_number/{phone_number}/actions/verify` with the extracted `code` and `verify_profile_id` to verify

**Benefits over SMS OTP:** No SMS charges, faster delivery, works even with SMS delivery issues, harder to intercept.

## Custom SMS Templates

Both Twilio Verify and Telnyx Verify support custom verification templates, but they select them at different scopes:

- A Twilio verification can pass `TemplateSid`, and a Twilio Verify Service can set `DefaultTemplateSid`.
- Telnyx attaches a template to a Verify Profile through `sms.messaging_template_id`.

Map a Twilio service default template to the equivalent Telnyx profile setting. If the Twilio application selects different `TemplateSid` values per verification, create/select Telnyx Verify Profiles with the corresponding templates; the Telnyx trigger request does not accept a per-request template ID.

Message templates are a **separate resource** managed via `/verify_profiles/templates` — not a parameter you pass when triggering a verification. The trigger call itself (`POST /verifications/sms`) accepts only `custom_code` and `timeout_secs` as optional parameters; there is no `template_id` parameter at trigger time. Create/manage templates first, then trigger the SMS verification normally:

```bash
# Create the template and capture its ID (separate resource)
if ! TEMPLATE_ID=$(curl -fsS -X POST https://api.telnyx.com/v2/verify_profiles/templates \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your {{app_name}} verification code is: {{code}}."}' \
  | jq -er '.data.id'); then
  echo "Verify template creation failed; profile was not changed" >&2
  exit 1
fi

# Read and preserve the profile's existing SMS settings, then select the new
# template. Replacing the nested `sms` object with only one key can erase other
# channel settings, so merge before PATCHing.
CURRENT_SMS=$(curl -fsS \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/verify_profiles/$TELNYX_VERIFY_PROFILE_ID" \
  | jq -ec '.data.sms // {}') || exit 1
CURRENT_TEMPLATE_ID=$(jq -r '.messaging_template_id // "unassigned"' \
  <<<"$CURRENT_SMS") || exit 1

TEMPLATE_UPDATE_APPROVAL="$TELNYX_VERIFY_PROFILE_ID|sms-template:$CURRENT_TEMPLATE_ID->$TEMPLATE_ID"
printf 'Verify template update approval token: %s\n' "$TEMPLATE_UPDATE_APPROVAL"
test "${TELNYX_APPROVE_VERIFY_TEMPLATE_UPDATE:-}" = "$TEMPLATE_UPDATE_APPROVAL" || {
  echo "Verify profile template update not approved" >&2; exit 1;
}

PATCH_BODY=$(jq -cn \
  --argjson sms "$CURRENT_SMS" \
  --arg template "$TEMPLATE_ID" \
  '{sms: ($sms + {messaging_template_id: $template})}')

curl -fsS -X PATCH "https://api.telnyx.com/v2/verify_profiles/$TELNYX_VERIFY_PROFILE_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$PATCH_BODY" || exit 1
```

```python
# Trigger SMS verification (optional params: custom_code, timeout_secs)
verification = client.verifications.trigger_sms(
    phone_number="+15559876543",
    verify_profile_id="YOUR_PROFILE_ID"
)
```

## Concept Mapping

| Twilio Concept | Telnyx Concept |
|---|---|
| Verify Service (`VA...`) | Verify Profile |
| Verification SID | Verification ID |
| Channel (`sms`, `call`, `whatsapp`, `email`) | Endpoint path: `POST /v2/verifications/{sms\|call\|flashcall\|whatsapp}` — the channel is chosen by the URL, not a request field (`type` is response-only); Telnyx Verify has no email channel |
| `approved` / `pending` | `accepted` / `rejected` |
| Rate limits (per Service) | Rate limits (per Profile) |
| Fraud Guard | Built-in fraud detection |

## Webhook Differences

Twilio Verify does not use webhooks for the direct VerificationCheck result; the check request returns its result synchronously.

Telnyx Verify likewise returns the direct code-check result synchronously as the verify action's `response_code`. If a webhook URL is configured on the Verify Profile, the currently documented delivery lifecycle notifications use these event names:

- `verify.sent` — the verification request was sent
- `verify.delivered` — the verification reached the destination
- `verify.failed` — delivery failed

Those three events report delivery state; they are not the only possible Verify notification contract. Telnyx also documents real-time completion notifications, but the public receiving-webhooks page does not currently enumerate a stable completion event name and payload alongside the delivery events. Confirm the completion event contract exposed by the target Verify Profile/API version before implementing an event-driven acceptance handler; do not infer acceptance from `verify.delivered`. For a direct code check, determine acceptance from the synchronous verify action's `response_code` (`accepted` or `rejected`).

## Testing

When migrating verify tests, the key change is the response field names.

### Mock Patterns

**Python (pytest/unittest):**
```python
# Twilio mock:
# @patch('twilio.rest.Client')
# def test_verify(mock_client):
#     mock_client.return_value.verify.v2.services('VA...').verification_checks.create.return_value.status = 'approved'

# Telnyx mock (v4 SDK — client.verifications.by_phone_number.actions.verify,
# mirroring POST /verifications/by_phone_number/{phone_number}/actions/verify):
@patch('your_module.client.verifications.by_phone_number.actions.verify')  # patch where client is used
def test_verify_code(mock_submit):
    mock_submit.return_value = type('obj', (object,), {
        'data': type('obj', (object,), {
            'phone_number': '+15559876543',
            'verify_profile_id': 'uuid-here',
            'response_code': 'accepted',  # NOT 'approved'
        })()
    })()
    result = verify_code('+15559876543', '123456')
    assert result.data.response_code == 'accepted'
```

**JavaScript (Jest):**
```javascript
jest.mock('telnyx', () => {
  return jest.fn().mockImplementation(() => ({
    verifications: {
      // mirrors client.verifications.byPhoneNumber.actions.verify(...)
      byPhoneNumber: {
        actions: {
          verify: jest.fn().mockResolvedValue({
            data: {
              phone_number: '+15559876543',
              verify_profile_id: 'uuid-here',
              response_code: 'accepted',
            }
          })
        }
      }
    }
  }));
});
```

### Assertion Changes

| Twilio Assertion | Telnyx Assertion |
|---|---|
| `assert result.status == 'approved'` | `assert result.data.response_code == 'accepted'` |
| `assert result.status == 'pending'` | `assert result.data.status == 'pending'` (on create) |
| `assert result.sid.startswith('VE')` | `assert result.data.verify_profile_id is not None` |
| `assert result.channel == 'sms'` | `assert result.data.type == 'sms'` |
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