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

View on GitHub
# Video Migration: Twilio Video to Telnyx Video Rooms

Migrate from Twilio Video (retired December 5, 2024) to the Telnyx Video Rooms API.

## Table of Contents

- [Overview](#overview)
- [Key Differences](#key-differences)
- [Concept Mapping](#concept-mapping)
- [Step 1: Create a Video Room](#step-1-create-a-video-room)
- [Step 2: Generate Client Tokens](#step-2-generate-client-tokens)
- [Step 3: Connect Clients via SDK](#step-3-connect-clients-via-sdk)
- [Step 4: Manage Participants](#step-4-manage-participants)
- [Step 5: Recording](#step-5-recording)
- [Room Sessions and Lifecycle](#room-sessions-and-lifecycle)
- [Client SDK Migration](#client-sdk-migration)
- [Compositions](#compositions)
- [API Endpoint Mapping](#api-endpoint-mapping)
- [Common Pitfalls](#common-pitfalls)

## Overview

Twilio retired its Video product on December 5, 2024. If you are migrating from Twilio Video, Telnyx Video Rooms provides a comparable platform for adding real-time audio and video capabilities to web, iOS, and Android applications.

Telnyx Video Rooms consists of:
- **REST API (v2)** for server-side room management, token generation, and recording
- **Client SDKs** (JavaScript, iOS, Android) for browser and mobile integration
- **Compositions API** for combining recordings into a single output

## Key Differences

1. **Twilio Video is retired** — As of December 5, 2024, Twilio Video is no longer available. Telnyx Video Rooms is actively supported.
2. **Room model** — Twilio used Room Types (Group, Peer-to-Peer, Go). Telnyx uses a single room model with configurable `max_participants`.
3. **Token format** — Twilio used Access Tokens (JWT with Video Grant). Telnyx uses Client Join Tokens (JWT) generated via a dedicated API endpoint.
4. **Refresh tokens** — Telnyx provides a Refresh Token alongside the Client Join Token for extending sessions without re-authenticating.
5. **Server-side participant control** — Telnyx provides REST API endpoints to mute, unmute, and kick participants from active sessions.
6. **Webhook signatures** — Twilio used HMAC-SHA1. Telnyx uses Ed25519.

## Concept Mapping

| Twilio Video Concept | Telnyx Equivalent | Notes |
|---|---|---|
| Room | Room | Created via `POST /v2/rooms` |
| Room SID | Room `id` (UUID) | Different ID format |
| Room Type (Group, P2P, Go) | `max_participants` setting | No named types; configure participant limit |
| Room UniqueName | `unique_name` | Same concept |
| Access Token (JWT + Video Grant) | Client Join Token (JWT) | Generated via `POST /v2/rooms/{id}/actions/generate_join_client_token` |
| N/A | Refresh Token | Provided with join token for session extension |
| Participant SID | Participant `id` | Managed via Sessions API |
| Room Session | Room Session | `GET /v2/rooms/{id}/sessions` to list |
| Composition | Composition | `POST /v2/room_compositions` |
| Recording | Recording | Top-level recording management (`GET /v2/room_recordings`) |
| Track (Audio/Video/Data) | Media streams | Managed via Client SDK |
| Room Status Callback | Webhook events on room | Configured via `webhook_event_url` |
| Twilio Video JS SDK | `@telnyx/video` JS SDK | Different API surface |
| Twilio Video iOS SDK | Telnyx Video iOS SDK | See iOS client SDK docs |
| Twilio Video Android SDK | Telnyx Video Android SDK | See Android client SDK docs |

## Step 1: Create a Video Room

### curl

```bash
# Twilio (no longer available)
curl -X POST "https://video.twilio.com/v1/Rooms" \
  -u "$TWILIO_SID:$TWILIO_AUTH_TOKEN" \
  -d "UniqueName=my-meeting" \
  -d "Type=group" \
  -d "MaxParticipants=10" \
  -d "RecordParticipantsOnConnect=true" \
  -d "StatusCallback=https://example.com/video-events"

# Telnyx
curl -X POST https://api.telnyx.com/v2/rooms \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_name": "my-meeting",
    "max_participants": 10,
    "enable_recording": true,
    "webhook_event_url": "https://example.com/video-events"
  }'
```

### Python

```python
# Twilio (no longer available)
from twilio.rest import Client
client = Client(account_sid, auth_token)
room = client.video.rooms.create(
    unique_name="my-meeting",
    type="group",
    max_participants=10,
    record_participants_on_connect=True,
    status_callback="https://example.com/video-events"
)

# Telnyx
from telnyx import Telnyx
client = Telnyx(api_key="YOUR_TELNYX_API_KEY")

room = client.rooms.create(
    unique_name="my-meeting",
    max_participants=10,
    enable_recording=True,
    webhook_event_url="https://example.com/video-events"
)
if room.data is None:
    raise RuntimeError("Telnyx room creation returned no data")
print(room.data.id)
```

### JavaScript

```javascript
// Twilio (no longer available)
const twilio = require('twilio');
const client = twilio(accountSid, authToken);
const room = await client.video.rooms.create({
  uniqueName: 'my-meeting',
  type: 'group',
  maxParticipants: 10,
  recordParticipantsOnConnect: true,
  statusCallback: 'https://example.com/video-events'
});

// Telnyx
const Telnyx = require('telnyx');
const client = new Telnyx({ apiKey: 'YOUR_TELNYX_API_KEY' });

const room = await client.rooms.create({
  unique_name: 'my-meeting',
  max_participants: 10,
  enable_recording: true,
  webhook_event_url: 'https://example.com/video-events'
});
console.log(room.data.id);
```

**Room creation parameters:**

| Parameter | Description |
|---|---|
| `unique_name` | Human-readable room identifier |
| `max_participants` | Maximum number of concurrent participants |
| `enable_recording` | Enable automatic recording (boolean) |
| `webhook_event_url` | URL for room and participant events |
| `webhook_event_failover_url` | Backup webhook URL |
| `webhook_timeout_secs` | Webhook delivery timeout |

**Room response fields:**

| Field | Description |
|---|---|
| `id` | Room UUID |
| `unique_name` | The name you assigned |
| `max_participants` | Configured limit |
| `enable_recording` | Recording status |
| `active_session_id` | UUID of the currently active session, if any |
| `created_at` | Creation timestamp |
| `updated_at` | Last update timestamp |

## Step 2: Generate Client Tokens

Clients need a JWT token to join a room. In Twilio, you generated Access Tokens server-side with a Video Grant. In Telnyx, you use a dedicated token generation endpoint.

### curl

```bash
# Twilio (no longer available) — generated server-side with SDK
# Required: AccountSID, API Key SID, API Key Secret, Room Name

# Telnyx
curl -X POST "https://api.telnyx.com/v2/rooms/$ROOM_ID/actions/generate_join_client_token" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token_ttl_secs": 3600,
    "token_ttl_secs": 600
  }'
```

### Python

```python
# Twilio (no longer available)
from twilio.jwt.access_token import AccessToken
from twilio.jwt.access_token.grants import VideoGrant
token = AccessToken(account_sid, api_key_sid, api_key_secret, identity="user-1")
token.add_grant(VideoGrant(room="my-meeting"))
jwt_token = token.to_jwt()

# Telnyx
from telnyx import Telnyx
client = Telnyx(api_key="YOUR_TELNYX_API_KEY")

token_response = client.rooms.actions.generate_join_client_token(
    room_id,
    refresh_token_ttl_secs=3600,
    token_ttl_secs=600
)
client_token = token_response.data.token
refresh_token = token_response.data.refresh_token
```

### JavaScript

```javascript
// Twilio (no longer available)
const { jwt: { AccessToken } } = require('twilio');
const { VideoGrant } = AccessToken;
const token = new AccessToken(accountSid, apiKeySid, apiKeySecret, { identity: 'user-1' });
token.addGrant(new VideoGrant({ room: 'my-meeting' }));
const jwtToken = token.toJwt();

// Telnyx
const Telnyx = require('telnyx');
const client = new Telnyx({ apiKey: 'YOUR_TELNYX_API_KEY' });

const tokenResponse = await client.rooms.actions.generateJoinClientToken(roomId, {
  refresh_token_ttl_secs: 3600,
  token_ttl_secs: 600
});
const clientToken = tokenResponse.data.token;
const refreshToken = tokenResponse.data.refresh_token;
```

The **Refresh Token** is a Telnyx-specific feature with no Twilio equivalent. Use it to extend a participant's session without generating a new join token from your server.

## Step 3: Connect Clients via SDK

### JavaScript Client

```javascript
// Twilio (no longer available)
import Video from 'twilio-video';
const room = await Video.connect(token, { name: 'my-meeting' });
room.on('participantConnected', participant => {
  console.log(`${participant.identity} joined`);
});

// Telnyx (@telnyx/video 1.0.2)
import { initialize } from '@telnyx/video';
const room = await initialize({ roomId, clientToken });
room.on('participant_joined', (participantId, state) => {
  console.log(`${participantId} joined`);
});
room.on('participant_left', (participantId, state) => {
  console.log(`${participantId} left`);
});
await room.connect();
```

**SDK event mapping:**

| Twilio Video JS Event | Telnyx Video JS Event | Notes |
|---|---|---|
| `participantConnected` | `participant_joined` | Callback receives participant ID and room state |
| `participantDisconnected` | `participant_left` | Callback receives participant ID and room state |
| `trackSubscribed` | `subscription_started` | Callback receives participant ID, stream key, and room state |
| `trackUnsubscribed` | `subscription_ended` | Callback receives participant ID, stream key, and room state |
| `disconnected` | `disconnected` | Same event name |
| `reconnecting` / `reconnected` | No direct event | Observe `state_changed` / `disconnected` and implement application reconnect handling |

## Step 4: Manage Participants

Telnyx provides server-side REST API endpoints for participant management that Twilio offered through its Data Track API or REST API. These actions operate on a room **session**, not on individual participant URLs. Set `participants` to the string `"all"` or to an array of participant UUIDs; when targeting all participants, `exclude` can list UUIDs to skip.

### Mute Participants

```bash
MUTE_EXCLUDE_ID="participant_id_to_keep_unmuted"
MUTE_APPROVAL="$SESSION_ID|mute|all|exclude:$MUTE_EXCLUDE_ID"
test -n "$SESSION_ID" -a -n "$MUTE_EXCLUDE_ID" || exit 1
printf 'Mute-all approval token: %s\n' "$MUTE_APPROVAL"
test "${TELNYX_APPROVE_ROOM_MUTATION:-}" = "$MUTE_APPROVAL" || {
  echo "Session-wide mute not approved" >&2; exit 1;
}
curl -fsS -X POST "https://api.telnyx.com/v2/room_sessions/$SESSION_ID/actions/mute" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -cn --arg id "$MUTE_EXCLUDE_ID" \
    '{participants: "all", exclude: [$id]}')" || exit 1
```

### Unmute Participants

```bash
UNMUTE_APPROVAL="$SESSION_ID|unmute|all|exclude:none"
test -n "$SESSION_ID" || exit 1
printf 'Unmute-all approval token: %s\n' "$UNMUTE_APPROVAL"
test "${TELNYX_APPROVE_ROOM_MUTATION:-}" = "$UNMUTE_APPROVAL" || {
  echo "Session-wide unmute not approved" >&2; exit 1;
}
curl -fsS -X POST "https://api.telnyx.com/v2/room_sessions/$SESSION_ID/actions/unmute" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"participants": "all", "exclude": []}' || exit 1
```

### Kick Participants

```bash
PARTICIPANT_ID="participant-id-to-kick"
KICK_APPROVAL="$SESSION_ID|$PARTICIPANT_ID"
test -n "$SESSION_ID" -a -n "$PARTICIPANT_ID" || exit 1
printf 'Kick participant %s from room session %s\n' "$PARTICIPANT_ID" "$SESSION_ID"
test "${TELNYX_APPROVE_ROOM_KICK:-}" = "$KICK_APPROVAL" || {
  echo "Participant kick not approved" >&2; exit 1;
}
jq -n --arg participant "$PARTICIPANT_ID" \
  '{participants: [$participant], exclude: []}' |
curl -fsS -X POST "https://api.telnyx.com/v2/room_sessions/$SESSION_ID/actions/kick" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

### List Participants

```bash
# All participants (filter by room via query params)
curl -X GET "https://api.telnyx.com/v2/room_participants" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

# Participants for a specific session
curl -X GET "https://api.telnyx.com/v2/room_sessions/$SESSION_ID/participants" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

## Step 5: Recording

Telnyx Video supports room-level recording. Enable recording when creating the room or update an existing room.

Recordings are exposed as a top-level resource. Filter the list by `room_id` to scope results to a specific room.

### List Recordings

```bash
curl -X GET -G --data-urlencode "filter[room_id]=$ROOM_ID" \
  "https://api.telnyx.com/v2/room_recordings" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

### View a Recording

```bash
curl -X GET "https://api.telnyx.com/v2/room_recordings/$RECORDING_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

### Delete Recordings

```bash
# Enumerate the exact recording IDs for one room and review the final set.
RECORDINGS=$(curl -fsS -G -H "Authorization: Bearer $TELNYX_API_KEY" \
  --data-urlencode "filter[room_id]=$ROOM_ID" \
  --data-urlencode "page[size]=250" \
  "https://api.telnyx.com/v2/room_recordings") || exit 1
RECORDING_IDS=$(jq -cer --arg room "$ROOM_ID" '
  select(.meta.total_pages == 1)
  | [.data[] | select(.room_id == $room) | .id]
  | select(length > 0 and all(.[]; type == "string" and test("\\S")))
  | unique | sort
' <<<"$RECORDINGS") || exit 1
: "${RECORDING_RECOVERY_PLAN:?Set to the reviewed backup location or irreversible-no-recovery}"
RECORDING_APPROVAL="$ROOM_ID|delete-recordings|$(jq -r 'join(",")' <<<"$RECORDING_IDS")|recovery:$RECORDING_RECOVERY_PLAN"
printf 'Recordings selected for irreversible deletion:\n%s\n' \
  "$(jq -r '.[]' <<<"$RECORDING_IDS")"
printf 'Reviewed recovery plan: %s\n' "$RECORDING_RECOVERY_PLAN"
printf 'Recording deletion approval token: %s\n' "$RECORDING_APPROVAL"
test "${TELNYX_APPROVE_RECORDING_DELETE:-}" = "$RECORDING_APPROVAL" || {
  echo "Recording deletion not approved" >&2; exit 1;
}

# Delete only the reviewed IDs; never issue a collection DELETE.
jq -r '.[]' <<<"$RECORDING_IDS" | while IFS= read -r recording_id; do
  curl -fsS -X DELETE \
    "https://api.telnyx.com/v2/room_recordings/$recording_id" \
    -H "Authorization: Bearer $TELNYX_API_KEY" || exit 1
done

```

Do not issue an unfiltered collection DELETE. For broader cleanup, enumerate
the exact recording IDs from a reviewed export and delete those IDs one at a
time after explicit confirmation.

**Recording comparison:**

| Aspect | Twilio Video (was) | Telnyx Video |
|---|---|---|
| Enable recording | `RecordParticipantsOnConnect` | `enable_recording` on room |
| Recording scope | Per-participant tracks | Per-room |
| Storage | Twilio media storage | Telnyx media storage |
| Composition | Compositions API | Compositions API |
| Download | REST API + media URL | REST API + media URL |

## Room Sessions and Lifecycle

A **Room Session** represents a single period of activity in a room. When the first participant joins, a session starts. When the last participant leaves, the session ends. A room can have multiple sessions over its lifetime.

```bash
# List sessions for a room
curl -X GET "https://api.telnyx.com/v2/rooms/$ROOM_ID/sessions" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

# View a specific session
curl -X GET "https://api.telnyx.com/v2/room_sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

# End a session (disconnect all participants)
END_APPROVAL="$SESSION_ID|end|all-participants"
test -n "$SESSION_ID" || exit 1
printf 'End-session approval token: %s\n' "$END_APPROVAL"
test "${TELNYX_APPROVE_ROOM_MUTATION:-}" = "$END_APPROVAL" || {
  echo "Ending the room session not approved" >&2; exit 1;
}
curl -fsS -X POST "https://api.telnyx.com/v2/room_sessions/$SESSION_ID/actions/end" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

**Room lifecycle comparison:**

| Twilio | Telnyx |
|---|---|
| Room auto-closes when empty | Session ends when empty; room persists |
| Room has single lifecycle | Room has multiple sessions |
| Complete a room via API | End a session via API |
| Room is a one-time resource | Room is reusable |

## Client SDK Migration

| Twilio SDK | Telnyx SDK | Install |
|---|---|---|
| `twilio-video` (npm) | `@telnyx/video` (npm) | `npm install @telnyx/video` |
| `TwilioVideo` (CocoaPods) | Telnyx Video iOS SDK | See iOS SDK docs |
| `com.twilio:video-android` | Telnyx Video Android SDK | See Android SDK docs |

The JavaScript SDK is the most mature Telnyx Video client SDK. For iOS and Android, consult the Telnyx developer documentation for the latest SDK availability and setup instructions.

## Compositions

Compositions combine individual participant recordings into a single media file. This is useful for archiving meetings or creating shareable recordings.

```bash
# Create a composition
# session_id, format, resolution, and video_layout are all optional.
# video_layout is an object describing named regions, not a preset string.
curl -X POST https://api.telnyx.com/v2/room_compositions \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "SESSION_ID",
    "format": "mp4",
    "resolution": "1280x720",
    "video_layout": {
      "main": {
        "z_pos": 1,
        "video_sources": ["*"]
      }
    }
  }'

# List compositions
curl -X GET "https://api.telnyx.com/v2/room_compositions" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

## API Endpoint Mapping

| Operation | Twilio Endpoint (was) | Telnyx Endpoint |
|---|---|---|
| Create room | `POST /v1/Rooms` | `POST /v2/rooms` |
| List rooms | `GET /v1/Rooms` | `GET /v2/rooms` |
| Get room | `GET /v1/Rooms/{SID}` | `GET /v2/rooms/{id}` |
| Update room | `POST /v1/Rooms/{SID}` | `PATCH /v2/rooms/{id}` |
| Delete room | N/A | `DELETE /v2/rooms/{id}` |
| Generate token | Server-side SDK (Access Token) | `POST /v2/rooms/{id}/actions/generate_join_client_token` |
| List participants | `GET /v1/Rooms/{SID}/Participants` | `GET /v2/room_participants` or `GET /v2/room_sessions/{session_id}/participants` |
| Mute participants | Client-side only | `POST /v2/room_sessions/{session_id}/actions/mute` |
| Kick participants | `POST /Participants/{SID} (Status=disconnected)` | `POST /v2/room_sessions/{session_id}/actions/kick` |
| List sessions | N/A | `GET /v2/rooms/{id}/sessions` or `GET /v2/room_sessions` |
| Get session | N/A | `GET /v2/room_sessions/{session_id}` |
| End session | `POST /Rooms/{SID} (Status=completed)` | `POST /v2/room_sessions/{session_id}/actions/end` |
| List recordings | `GET /v1/Rooms/{SID}/Recordings` | `GET /v2/room_recordings` |
| Get recording | `GET /v1/Recordings/{SID}` | `GET /v2/room_recordings/{id}` |
| Delete recording | `DELETE /v1/Recordings/{SID}` | `DELETE /v2/room_recordings/{id}` (single) or `DELETE /v2/room_recordings` (bulk) |
| Create composition | `POST /v1/Compositions` | `POST /v2/room_compositions` |

## Common Pitfalls

1. **Token generation is server-side only** — Unlike Twilio where you generated Access Tokens using SDK helper classes, Telnyx token generation is a REST API call. Your server must call the Telnyx API and pass the token to the client.

2. **Room type does not exist** — Twilio had Group, Peer-to-Peer, and Go room types. Telnyx uses a single room model. Set `max_participants` to control room capacity. For 1:1 calls, set `max_participants: 2`.

3. **Client SDK event names differ** — `participantConnected` becomes `participant_joined`, `participantDisconnected` becomes `participant_left`. Update all event listeners.

4. **Sessions vs rooms** — Telnyx rooms are persistent and reusable. A single room can host multiple sessions. If your Twilio code creates a new room per meeting, you may want to reuse Telnyx rooms and track sessions instead.

5. **Refresh tokens are new** — Telnyx provides refresh tokens for extending sessions. Implement refresh logic in your client to avoid disconnections when the join token expires.

6. **Recording scope is room-level** — Twilio recorded individual participant tracks. Telnyx records at the room level. Use the Compositions API to combine recordings if needed.

7. **Webhook payload structure** — Telnyx webhooks use the standard nested structure (`event.data.event_type`, `event.data.payload`). This differs from Twilio's Status Callback format.

8. **Sub-resources are not nested under `/rooms/{id}/...` (with one exception) — but they ARE session-scoped where that is the natural parent.** Recordings and compositions are top-level only (`/room_recordings`, `/room_compositions`); scope them to a room by filtering on `room_id`. Participants are listed either account-wide (`GET /v2/room_participants`) **or session-scoped (`GET /v2/room_sessions/{session_id}/participants`) — use the session-scoped route when you want the participants of one session**, since participants carry `session_id`, not `room_id`. Under `/rooms/{room_id}/...` the only valid nested route is `GET /v2/rooms/{room_id}/sessions`; per-session actions (get, end, mute, kick) live at `/room_sessions/{session_id}`.
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