无法通过Twilio电话启动双向WebSocket媒体流的问题排查

需求目标 #

• 用户拨打Twilio号码
• Twilio连接到部署的WebSocket服务
• 实时监听音频流并发送消息

现有实现代码 #

AWS Lambda 返回TWiML端点代码 #

def hello(event, context):
    voice_response = VoiceResponse()
    start = Start()
    connect = Connect()
    voice_response.say("Hi this is Charles, one moment while I start the stream")
    # NOTE: Remember to change this each time as needed if local/dev
    local_stream_url = "ws://2.tcp.ngrok.io:15337"
    connect.stream(url=local_stream_url)
    start.append(connect)
    voice_response.append(start)
    # Theoretically need to give it time to handle connection etc.
    voice_response.pause(length=10)

    response = {
        'statusCode': 200,
        'headers': {
            'Content-Type': 'text/xml'
        },
        'body': str(voice_response)
    }

    return response

本地WebSocket服务器代码 #

#!/usr/bin/env python

import asyncio
import websockets

async def handler(websocket):
    while True:
        message = await websocket.recv()
        print(message)


async def main():
    async with websockets.serve(handler, "", 3000):
        await asyncio.Future()  # run forever

if __name__ == "__main__":
    asyncio.run(main())

ngrok配置信息 #

Announcing ngrok-go: embed ngrok into your Go apps as a net.Listener: https://ngrok.com/golang                                                                                    

Session Status                online                                                                                                                                              
Account                       <me> (Plan: Personal)                                                                                                                       
Version                       3.2.1                                                                                                                                               
Region                        United States (us)                                                                                                                                  
Latency                       22ms                                                                                                                                                
Web Interface                 http://127.0.0.1:4040                                                                                                                               
Forwarding                    tcp://2.tcp.ngrok.io:15337 -> localhost:3000                                                                                                        

问题：Error - 11100 #

Twilio返回该错误，文档提示需提交包含http/https协议的完整URL，但此处需使用ws/wss协议，以下是排查与修改点：

1. 修正ngrok转发类型 #

当前使用的是tcp转发，Twilio的WebSocket连接需要通过HTTP协议完成握手升级，因此必须改用http转发命令：

ngrok http 3000

执行后会得到类似如下的转发地址：

Forwarding                    https://xxxx-xx-xx-xx-xx.ngrok-free.app -> http://localhost:3000

此时对应的WebSocket URL应为wss://xxxx-xx-xx-xx-xx.ngrok-free.app（加密，推荐）或ws://xxxx-xx-xx-xx-xx.ngrok-free.app（非加密）。

2. 验证TWiML结构正确性 #

确认生成的TWiML标签嵌套逻辑：必须是<Response> → <Start> → <Connect> → <Stream>，你的代码逻辑符合要求，但需确保生成的XML中url属性使用正确的ws/wss协议地址。

3. 协议与转发地址匹配 #

• 使用ngrok http转发时，URL协议必须对应ws://（非加密）或wss://（加密）
• 禁止使用tcp转发地址，因为Twilio无法通过裸TCP连接完成WebSocket握手

补充Twilio文档说明 #

• <Stream>标签用于建立双向媒体流，URL必须使用ws或wss协议
• 连接需完成标准WebSocket握手，因此必须通过HTTP/HTTPS转发通道，而非裸TCP转发

内容的提问来源于stack exchange，提问作者ObjectNameDisplay