Back to Details

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 ProductTelnyx EquivalentMigration Path
Programmable Voice (TwiML)TeXMLNear drop-in XML compatibility
Programmable Voice (REST)Call Control APIEvent-driven, WebSocket-based
Programmable MessagingMessaging APINew SDK integration
Elastic SIP TrunkingSIP TrunkingDirect replacement
Voice SDK (WebRTC)WebRTC SDKs (JS, iOS, Android, Flutter, RN)Concept remapping
Phone NumbersNumber ManagementFastPort for same-day porting
Twilio VerifyVerify APIDifferent API surface, same functionality
Twilio LookupNumber LookupDirect replacement
Twilio Video (retired Dec 2024)Video Rooms APITelnyx still supports video
Twilio Fax (deprecated)Programmable FaxTelnyx still supports fax
Super SIM / IoTIoT SIM Cards650+ 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 MessagingMessaging API新SDK集成
Elastic SIP TrunkingSIP Trunking直接替代
Voice SDK (WebRTC)WebRTC SDKs (JS、iOS、Android、Flutter、RN)概念重映射
Phone NumbersNumber Management通过FastPort实现当日号码移植
Twilio VerifyVerify APIAPI接口不同，但功能一致
Twilio LookupNumber Lookup直接替代
Twilio Video（2024年12月停用）Video Rooms APITelnyx仍支持视频服务
Twilio Fax（已弃用）Programmable FaxTelnyx仍支持传真服务
Super SIM / IoTIoT 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

Twilio

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

Telnyx

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

Set your public key for webhook validation

telnyx.public_key = "YOUR_TELNYX_PUBLIC_KEY"
telnyx.public_key = "YOUR_TELNYX_PUBLIC_KEY"

In your webhook handler:

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
);
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
);

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"
or 
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

Twilio

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

Telnyx

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

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

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

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:
  1. Update all webhook URLs to point to your Telnyx-configured endpoints
  2. Replace all Twilio signature validation with Telnyx Ed25519 validation
  3. Update credential storage (API keys, public keys)
  4. Test webhook delivery in the Telnyx Mission Control Portal
  5. Verify number assignments (each number must be assigned to a connection or messaging profile)
  6. Update monitoring/alerting for Telnyx-specific status codes and error formats
  7. Update any Twilio status callback URLs to Telnyx webhook format
完成任何产品的迁移后：
  1. 将所有Webhook URL更新为指向你的Telnyx配置端点
  2. 将所有Twilio签名验证替换为Telnyx Ed25519验证
  3. 更新凭证存储（API密钥、公钥）
  4. 在Telnyx Mission Control门户中测试Webhook交付
  5. 验证号码分配（每个号码必须分配给连接或消息配置文件）
  6. 更新监控/告警以适配Telnyx特定的状态码和错误格式
  7. 将所有Twilio状态回调URL更新为Telnyx Webhook格式

Related Skills in This Repo

本仓库中的相关Skill

After migration, these skills provide deeper coverage for ongoing development:
Migration AreaRelated SkillsWhat 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

资源