telnyx-twilio-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Twilio to Telnyx Migration

从Twilio迁移至Telnyx

One-stop guide for migrating from Twilio to Telnyx. This skill covers every product area with step-by-step migration paths, code examples, and validation scripts.

Standalone skill: This skill is fully self-contained. For deeper SDK-specific code examples after migration, install the relevant language plugin (
telnyx-python
,
telnyx-javascript
,
telnyx-go
,
telnyx-java
, or
telnyx-ruby
). For client-side WebRTC, install
telnyx-webrtc-client
.

这是一份从Twilio迁移至Telnyx的一站式指南。本Skill涵盖所有产品领域，提供分步迁移路径、代码示例和验证脚本。

独立Skill：本Skill完全独立。迁移后如需更深入的特定SDK代码示例，请安装相关语言插件（
telnyx-python
,
telnyx-javascript
,
telnyx-go
,
telnyx-java
, 或
telnyx-ruby
）。对于客户端WebRTC，请安装
telnyx-webrtc-client
。

Preflight Check

预检查

Before starting any migration, validate your environment:

bash

bash {baseDir}/scripts/preflight-check.sh

This checks for a valid

TELNYX_API_KEY

, API connectivity, and detects any installed Twilio SDKs.

开始任何迁移前，请验证你的环境：

bash

bash {baseDir}/scripts/preflight-check.sh

此脚本会检查有效的

TELNYX_API_KEY

、API连通性，并检测已安装的Twilio SDK。

Product Mapping (Quick Reference)

产品映射（快速参考）

Twilio Product	Telnyx Equivalent	Migration Path
Programmable Voice (TwiML)	TeXML	Near drop-in XML compatibility
Programmable Voice (REST)	Call Control API	Event-driven, WebSocket-based
Programmable Messaging	Messaging API	New SDK integration
Elastic SIP Trunking	SIP Trunking	Direct replacement
Voice SDK (WebRTC)	WebRTC SDKs (JS, iOS, Android, Flutter, RN)	Concept remapping
Phone Numbers	Number Management	FastPort for same-day porting
Twilio Verify	Verify API	Different API surface, same functionality
Twilio Lookup	Number Lookup	Direct replacement
Twilio Video (retired Dec 2024)	Video Rooms API	Telnyx still supports video
Twilio Fax (deprecated)	Programmable Fax	Telnyx still supports fax
Super SIM / IoT	IoT SIM Cards	650+ networks, 180+ countries

For the complete mapping including Telnyx-only products and unsupported Twilio products, read:

{baseDir}/references/product-mapping.md

Twilio产品	Telnyx等效产品	迁移路径
Programmable Voice (TwiML)	TeXML	近乎直接兼容的XML
Programmable Voice (REST)	Call Control API	事件驱动、基于WebSocket
Programmable Messaging	Messaging API	新SDK集成
Elastic SIP Trunking	SIP Trunking	直接替代
Voice SDK (WebRTC)	WebRTC SDKs (JS、iOS、Android、Flutter、RN)	概念重映射
Phone Numbers	Number Management	通过FastPort实现当日号码移植
Twilio Verify	Verify API	API接口不同，但功能一致
Twilio Lookup	Number Lookup	直接替代
Twilio Video（2024年12月停用）	Video Rooms API	Telnyx仍支持视频服务
Twilio Fax（已弃用）	Programmable Fax	Telnyx仍支持传真服务
Super SIM / IoT	IoT SIM Cards	覆盖650+网络、180+国家

如需完整的产品映射（包括Telnyx专属产品和不支持的Twilio产品），请阅读：

{baseDir}/references/product-mapping.md

Universal Changes (All Migrations)

通用变更（所有迁移适用）

These four changes apply regardless of which Twilio product you are migrating.

以下四项变更适用于所有Twilio产品的迁移。

1. Authentication

1. 认证

Twilio uses Basic Auth with Account SID + Auth Token. Telnyx uses Bearer Token with an API Key v2.

bash

undefined

Twilio使用基于Account SID + Auth Token的基础认证。Telnyx使用基于API Key v2的Bearer Token认证。

bash

undefined

Twilio

curl -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"
https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json

Telnyx

curl -H "Authorization: Bearer $TELNYX_API_KEY"
https://api.telnyx.com/v2/messages


Get your API key at https://portal.telnyx.com/#/app/api-keys

curl -H "Authorization: Bearer $TELNYX_API_KEY"
https://api.telnyx.com/v2/messages


请在https://portal.telnyx.com/#/app/api-keys获取你的API密钥。

2. Webhook Signature Validation

2. Webhook签名验证

Twilio signs webhooks with HMAC-SHA1 (symmetric, uses auth token). Telnyx uses Ed25519 (asymmetric, uses a public key). This is the most common breaking change.

Get your public key at https://portal.telnyx.com/#/app/account/public-key

Python:

python

import telnyx

Twilio使用HMAC-SHA1（对称加密，使用auth token）签署Webhook。Telnyx使用Ed25519（非对称加密，使用公钥）。这是最常见的破坏性变更。

请在https://portal.telnyx.com/#/app/account/public-key获取你的公钥。

Python:

python

import telnyx

Set your public key for webhook validation

telnyx.public_key = "YOUR_TELNYX_PUBLIC_KEY"

In your webhook handler:

from telnyx.webhook import WebhookSignatureVerifier signature = request.headers.get("telnyx-signature-ed25519") timestamp = request.headers.get("telnyx-timestamp") WebhookSignatureVerifier.verify(request.body, signature, timestamp)


**Node.js:**
```javascript
const telnyx = require('telnyx')('YOUR_API_KEY');
telnyx.webhooks.signature.verifySignature(
  payload,
  request.headers['telnyx-signature-ed25519'],
  request.headers['telnyx-timestamp'],
  PUBLIC_KEY
);


**Node.js:**
```javascript
const telnyx = require('telnyx')('YOUR_API_KEY');
telnyx.webhooks.signature.verifySignature(
  payload,
  request.headers['telnyx-signature-ed25519'],
  request.headers['telnyx-timestamp'],
  PUBLIC_KEY
);

3. Webhook Payload Structure

3. Webhook负载结构

Twilio sends flat key-value pairs. Telnyx nests event data under a

data

object:

json

// Twilio webhook payload
{ "MessageSid": "SM...", "From": "+1555...", "Body": "Hello" }

// Telnyx webhook payload
{
  "data": {
    "event_type": "message.received",
    "payload": {
      "id": "...",
      "from": { "phone_number": "+1555..." },
      "text": "Hello"
    }
  }
}

Twilio发送扁平的键值对。Telnyx将事件数据嵌套在

data

对象中：

json

// Twilio webhook payload
{ "MessageSid": "SM...", "From": "+1555...", "Body": "Hello" }

// Telnyx webhook payload
{
  "data": {
    "event_type": "message.received",
    "payload": {
      "id": "...",
      "from": { "phone_number": "+1555..." },
      "text": "Hello"
    }
  }
}

4. Recording Defaults

4. 录音默认设置

Twilio defaults to single-channel recordings. Telnyx defaults to dual-channel (each party on a separate channel). To match Twilio behavior, explicitly set

channels="single"

recordingChannels="single"

in your TeXML or API calls.

Twilio默认生成单声道录音。Telnyx默认生成双声道（每一方在单独声道）。如需匹配Twilio的行为，请在TeXML或API调用中显式设置

channels="single"

或

recordingChannels="single"

。

Migration Guides by Product

按产品分类的迁移指南

Voice: TwiML to TeXML

语音：从TwiML到TeXML

TeXML is Telnyx's TwiML-compatible XML markup for voice applications. Most TwiML documents work with minimal changes.

Quick validation -- check your existing TwiML files for compatibility:

bash

bash {baseDir}/scripts/validate-texml.sh /path/to/your/twiml.xml

The script reports unsupported verbs, attribute differences, and Telnyx-only features you can adopt.

Step-by-step migration process (includes Call Control API as an alternative, client state patterns, bridge/link_to, caller ID policy, and subdomains): Read

{baseDir}/references/voice-migration.md

Complete TeXML verb reference (all 15 verbs + 8 nouns with attributes, nesting rules, and examples): Read

{baseDir}/references/texml-verbs.md

Key facts:

TeXML supports all standard TwiML verbs:

<Say>

<Play>

<Gather>

<Dial>

<Record>

<Hangup>

<Pause>

<Redirect>

<Reject>

<Refer>

<Enqueue>

<Leave>

Telnyx adds:
```
<Start>
```
,
```
<Stop>
```
,
```
<Connect>
```
(for async services)
Telnyx-only nouns:
```
<Transcription>
```
(real-time STT),
```
<Suppression>
```
(audio suppression),
```
<Siprec>
```
(SIPREC recording)
```
<Gather>
```
supports multiple STT engines: Google, Telnyx, Deepgram, Azure
```
<Say>
```
supports ElevenLabs voices alongside Polly
```
<Pay>
```
has no TeXML equivalent
Telnyx also offers the Call Control API — an imperative, event-driven alternative to XML. Use it for complex conditional logic, real-time call manipulation, or state-machine workflows

TeXML是Telnyx推出的与TwiML兼容的语音应用XML标记语言。大多数TwiML文档只需少量修改即可使用。

快速验证 -- 检查现有TwiML文件的兼容性：

bash

bash {baseDir}/scripts/validate-texml.sh /path/to/your/twiml.xml

该脚本会报告不支持的动词、属性差异以及可采用的Telnyx专属功能。

分步迁移流程（包括作为替代方案的Call Control API、客户端状态模式、bridge/link_to、来电显示策略和子域名）：请阅读

{baseDir}/references/voice-migration.md

完整TeXML动词参考（所有15个动词 + 8个名词，包含属性、嵌套规则和示例）：请阅读

{baseDir}/references/texml-verbs.md

关键要点：

TeXML支持所有标准TwiML动词：

<Say>

<Play>

<Gather>

<Dial>

<Record>

<Hangup>

<Pause>

<Redirect>

<Reject>

<Refer>

<Enqueue>

<Leave>

Telnyx新增：
```
<Start>
```
,
```
<Stop>
```
,
```
<Connect>
```
（用于异步服务）
Telnyx专属名词：
```
<Transcription>
```
（实时语音转文字）、
```
<Suppression>
```
（音频抑制）、
```
<Siprec>
```
（SIPREC录音）
```
<Gather>
```
支持多种语音转文字引擎：Google、Telnyx、Deepgram、Azure
```
<Say>
```
支持ElevenLabs语音以及Polly
```
<Pay>
```
没有TeXML等效项
Telnyx还提供Call Control API —— 这是XML的命令式、事件驱动替代方案，适用于复杂的条件逻辑、实时通话操作或状态机工作流

Messaging

消息服务

Migrate from Twilio Programmable Messaging to the Telnyx Messaging API. This is a new SDK integration, not a drop-in replacement.

Read

{baseDir}/references/messaging-migration.md

Quick comparison:

python

undefined

从Twilio Programmable Messaging迁移至Telnyx Messaging API。这是新的SDK集成，而非直接替代。

请阅读

{baseDir}/references/messaging-migration.md

快速对比：

python

undefined

Twilio

from twilio.rest import Client client = Client(account_sid, auth_token) message = client.messages.create(to="+1555...", from_="+1666...", body="Hello")

Telnyx

import telnyx telnyx.api_key = "YOUR_API_KEY" message = telnyx.Message.create(to="+1555...", from_="+1666...", text="Hello")

undefined

import telnyx telnyx.api_key = "YOUR_API_KEY" message = telnyx.Message.create(to="+1555...", from_="+1666...", text="Hello")

undefined

WebRTC / Voice SDK

Migrate from Twilio Voice SDK to Telnyx WebRTC SDKs. Key architectural difference: Telnyx allows direct browser-to-PSTN dialing without a server webhook.

Read

{baseDir}/references/webrtc-migration.md

Covers: SDK mapping, TwiML endpoint analysis (DELETE vs CONVERT decision tree), credential lifecycle (per-session, not per-call), token refresh, CDN vs npm pitfalls, contact center patterns (conferences not always needed, SIP headers for passing data, URI dialing, call parking).

Enhanced coverage: Install the
telnyx-webrtc-client
plugin for platform-specific implementation guides (JavaScript, iOS, Android, Flutter, React Native).

从Twilio Voice SDK迁移至Telnyx WebRTC SDK。关键架构差异：Telnyx允许浏览器直接拨打PSTN，无需服务器Webhook。

请阅读

{baseDir}/references/webrtc-migration.md

涵盖内容：SDK映射、TwiML端点分析（DELETE vs CONVERT决策树）、凭证生命周期（按会话而非按通话）、令牌刷新、CDN vs npm的陷阱、联络中心模式（不一定需要会议、传递数据的SIP头、URI拨号、通话驻留）。

扩展内容：安装
telnyx-webrtc-client
插件以获取平台特定的实现指南（JavaScript、iOS、Android、Flutter、React Native）。

Number Porting (FastPort)

号码移植（FastPort）

Move your phone numbers from Twilio to Telnyx programmatically. FastPort provides real-time LOA validation and on-demand activation for US/Canada numbers.

Read

{baseDir}/references/number-porting.md

通过编程方式将你的电话号码从Twilio迁移至Telnyx。FastPort为美国/加拿大号码提供实时LOA验证和按需激活。

请阅读

{baseDir}/references/number-porting.md

Verify / 2FA

Verify / 双因素认证

Migrate from Twilio Verify to Telnyx Verify API. Supports SMS, voice, flash calling, and PSD2 verification methods.

Read

{baseDir}/references/verify-migration.md

从Twilio Verify迁移至Telnyx Verify API。支持SMS、语音、闪呼以及PSD2验证方式。

请阅读

{baseDir}/references/verify-migration.md

Scripts

脚本

validate-texml.sh

Analyzes TwiML/TeXML XML files for compatibility issues:

bash

bash {baseDir}/scripts/validate-texml.sh /path/to/file.xml

Reports:

Errors: Unsupported verbs with no TeXML equivalent
Warnings: Attributes with different defaults or behavior
Info: Telnyx-only features you could adopt

分析TwiML/TeXML XML文件的兼容性问题：

bash

bash {baseDir}/scripts/validate-texml.sh /path/to/file.xml

报告内容：

错误：无TeXML等效项的不支持动词
警告：默认值或行为不同的属性
信息：可采用的Telnyx专属功能

preflight-check.sh

Validates migration environment readiness:

bash

bash {baseDir}/scripts/preflight-check.sh

Checks:

```
TELNYX_API_KEY
```
environment variable
API connectivity to
```
api.telnyx.com
```
Installed Twilio/Telnyx SDKs (Python, Node.js, Ruby, Go, Java)

验证迁移环境是否就绪：

bash

bash {baseDir}/scripts/preflight-check.sh

检查项：

```
TELNYX_API_KEY
```
环境变量
与
```
api.telnyx.com
```
的API连通性
已安装的Twilio/Telnyx SDK（Python、Node.js、Ruby、Go、Java）

Post-Migration Checklist

迁移后检查清单

After completing migration for any product:

Update all webhook URLs to point to your Telnyx-configured endpoints
Replace all Twilio signature validation with Telnyx Ed25519 validation
Update credential storage (API keys, public keys)
Test webhook delivery in the Telnyx Mission Control Portal
Verify number assignments (each number must be assigned to a connection or messaging profile)
Update monitoring/alerting for Telnyx-specific status codes and error formats
Update any Twilio status callback URLs to Telnyx webhook format

完成任何产品的迁移后：

将所有Webhook URL更新为指向你的Telnyx配置端点
将所有Twilio签名验证替换为Telnyx Ed25519验证
更新凭证存储（API密钥、公钥）
在Telnyx Mission Control门户中测试Webhook交付
验证号码分配（每个号码必须分配给连接或消息配置文件）
更新监控/告警以适配Telnyx特定的状态码和错误格式
将所有Twilio状态回调URL更新为Telnyx Webhook格式

Related Skills in This Repo

本仓库中的相关Skill

After migration, these skills provide deeper coverage for ongoing development:

Migration Area	Related Skills	What They Cover
Voice (Call Control)	`telnyx-voice-*`	dial (with `bridge_on_answer` , `bridge_intent` , `link_to` , `supervisor_role` , `sip_headers` , `custom_headers` , `park_after_unbridge` ), bridge, transfer, answer, hangup — all with optional params and webhook payload schemas
Voice (Advanced)	`telnyx-voice-advanced-*`	`client_state` on all commands, `updateClientState` , SIP Refer with `custom_headers` / `sip_headers` , DTMF send, SIPREC, noise suppression — with webhook payload field tables
Voice (Conferencing)	`telnyx-voice-conferencing-*`	conference create (with `max_participants` , `hold_audio_url` , `region` ), join (with `supervisor_role` , `whisper_call_control_ids` , `mute` , `hold` ), leave (returns to parked state), recording, speak, play — with webhook payload schemas
Voice (Gather/IVR)	`telnyx-voice-gather-*`	DTMF gathering, AI gather, gather using speak/audio — with webhook payload schemas for `call.gather.ended`
Voice (Media)	`telnyx-voice-media-*`	play audio, start/stop recording, streaming — with optional params for recording format, channels, track
Voice (TeXML REST)	`telnyx-texml-*`	TeXML API CRUD (JS only — other langs use Call Control)
WebRTC (Backend)	`telnyx-webrtc-*`	telephony credential create/token, SIP connection setup
WebRTC (Client)	`telnyx-webrtc-client-*`	platform SDKs (JS, iOS, Android, Flutter, React Native) — custom SIP headers, push notifications
SIP / Trunking	`telnyx-sip-*`	outbound voice profiles (with `whitelisted_destinations` , `traffic_type` , `calling_window` , `concurrent_call_limit` ), credential connections (with `sip_uri_calling_preference` , `inbound` / `outbound` objects, `encrypted_media` ), IP/FQDN connections
Messaging	`telnyx-messaging-*`	send/receive SMS/MMS with optional params and webhook payload schemas
Numbers	`telnyx-numbers-` , `telnyx-porting-in-`	number management, porting
Verify	`telnyx-verify-*`	verification API (SMS, voice, flash calling)

Install the relevant language plugin (

telnyx-python

telnyx-javascript

telnyx-go

telnyx-java

, or

telnyx-ruby

) to access these skills.

迁移完成后，以下Skill提供更深入的持续开发内容：

迁移领域	相关Skill	涵盖内容
语音 (Call Control)	`telnyx-voice-*`	拨号（支持 `bridge_on_answer` , `bridge_intent` , `link_to` , `supervisor_role` , `sip_headers` , `custom_headers` , `park_after_unbridge` ）、桥接、转接、接听、挂断 —— 均包含可选参数和Webhook负载Schema
语音 (高级)	`telnyx-voice-advanced-*`	所有命令的 `client_state` 、 `updateClientState` 、带 `custom_headers` / `sip_headers` 的SIP Refer、DTMF发送、SIPREC、噪声抑制 —— 包含Webhook负载字段表
语音 (会议)	`telnyx-voice-conferencing-*`	会议创建（支持 `max_participants` , `hold_audio_url` , `region` ）、加入（支持 `supervisor_role` , `whisper_call_control_ids` , `mute` , `hold` ）、离开（返回驻留状态）、录音、语音播报、播放 —— 包含Webhook负载Schema
语音 (Gather/IVR)	`telnyx-voice-gather-*`	DTMF收集、AI收集、通过语音/音频收集 —— 包含 `call.gather.ended` 的Webhook负载Schema
语音 (媒体)	`telnyx-voice-media-*`	播放音频、开始/停止录音、流传输 —— 包含录音格式、声道、音轨的可选参数
语音 (TeXML REST)	`telnyx-texml-*`	TeXML API增删改查（仅JS支持 —— 其他语言使用Call Control）
WebRTC (后端)	`telnyx-webrtc-*`	电话凭证创建/令牌、SIP连接设置
WebRTC (客户端)	`telnyx-webrtc-client-*`	平台SDK（JS、iOS、Android、Flutter、React Native） —— 自定义SIP头、推送通知
SIP / 中继	`telnyx-sip-*`	外呼语音配置文件（支持 `whitelisted_destinations` , `traffic_type` , `calling_window` , `concurrent_call_limit` ）、凭证连接（支持 `sip_uri_calling_preference` , `inbound` / `outbound` 对象、 `encrypted_media` ）、IP/FQDN连接
消息服务	`telnyx-messaging-*`	发送/接收SMS/MMS —— 包含可选参数和Webhook负载Schema
号码	`telnyx-numbers-` , `telnyx-porting-in-`	号码管理、号码移植
Verify	`telnyx-verify-*`	验证API（SMS、语音、闪呼）

请安装相关语言插件（

telnyx-python

telnyx-javascript

telnyx-go

telnyx-java

, 或

telnyx-ruby

）以访问这些Skill。

Resources

资源

Telnyx Mission Control Portal: https://portal.telnyx.com
Telnyx Developer Docs: https://developers.telnyx.com
Telnyx API Reference: https://developers.telnyx.com/api/overview
Telnyx Status Page: https://status.telnyx.com
Telnyx Support: https://support.telnyx.com

Telnyx Mission Control门户: https://portal.telnyx.com
Telnyx开发者文档: https://developers.telnyx.com
Telnyx API参考: https://developers.telnyx.com/api/overview
Telnyx状态页面: https://status.telnyx.com
Telnyx支持: https://support.telnyx.com