借助 Twilio 快速入门 OpenAI 实时 API

将 OpenAI 的实时 API 与 Twilio 的电话呼叫功能相结合，构建一个 AI 电话助手。

快速设置

打开三个终端窗口：

终端	用途	快速参考（更多内容见下文）
1	运行 webapp	npm run dev
2	运行 websocket-server	npm run dev
3	运行 ngrok	ngrok http 8081

请确保 webapp/.env 和 websocket-server/.env 中的所有环境变量都已正确设置。更多内容请参阅 完整设置 部分。

概述

此仓库实现了基于实时 API 和 Twilio 的电话助手，主要包含两个部分：webapp 和 websocket-server。

1. webapp: 一个 NextJS 应用程序，用作呼叫配置和通话记录的前端。
2. websocket-server: 一个 Express 后端，负责处理来自 Twilio 的连接、将其与实时 API 相连，并将消息转发到前端。

Twilio 使用 TwiML（一种 XML 格式）来指定如何处理电话呼叫。当有来电时，我们会指示 Twilio 启动一条双向流到我们的后端，在那里我们将呼叫与实时 API 之间的消息进行转发。（{{WS_URL}} 将被替换为我们的 WebSocket 端点。）

<!-- 用于启动双向流的 TwiML -->

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>已连接</Say>
  <Connect>
    <Stream url="{{WS_URL}}" />
  </Connect>
  <Say>已断开</Say>
</Response>

我们使用 ngrok 来使我们的服务器能够被 Twilio 访问。

一次电话呼叫的流程

设置

1. 我们运行 ngrok，使我们的服务器能够被 Twilio 访问。
2. 我们将 Twilio 的 Webhook 设置为我们的 ngrok 地址。
3. 前端连接到后端（wss://[your_backend]/logs），准备接听来电。

通话

1. 有人拨打由 Twilio 管理的号码。
2. Twilio 查询 Webhook（http://[your_backend]/twiml）以获取 TwiML 指令。
3. Twilio 打开一条双向流到后端（wss://[your_backend]/call）。
4. 后端连接到实时 API，并开始转发消息：
   • 在 Twilio 和实时 API 之间
   • 在前端和实时 API 之间

函数调用

此演示模拟了函数调用，以便您可以提供示例响应。在实际应用中，您可以处理函数调用、执行一些代码，然后将响应返回给模型。

完整设置

1. 确保您的 身份验证与环境变量 已正确配置。

2. 运行 webapp。

cd webapp
npm install
npm run dev

3. 运行 websocket 服务器。

cd websocket-server
npm install
npm run dev

详细的身份验证与环境变量

OpenAI 和 Twilio

请在 webapp/.env 和 websocket-server 中设置您的凭据——可参考 webapp/.env.example 和 websocket-server.env.example。

Ngrok

Twilio 需要能够访问您的 WebSocket 服务器。如果您在本地运行，端口默认是不可访问的。ngrok 可以临时使这些端口对外可用。

我们已将 websocket-server 默认设置为在端口 8081 上运行，因此我们将转发该端口。

ngrok http 8081

请记下“转发”URL。（例如：https://54c5-35-170-32-42.ngrok-free.app）

WebSocket URL

现在，您的服务器应在运行时可通过“转发”URL 访问，因此请在 websocket-server/.env 中设置 PUBLIC_URL。可参考 websocket-server/.env.example。

其他说明

此仓库尚未经过优化，安全措施也有待改进。请仅将其作为参考，并在部署前务必对您的应用程序进行安全和工程方面的审计！

OpenAI Realtime API + Twilio 电话助手快速上手指南

本指南帮助中国开发者快速搭建基于 OpenAI Realtime API 和 Twilio 的 AI 电话助手演示项目。

环境准备

系统要求

• Node.js (推荐 v18 或更高版本)
• npm 或 yarn 包管理器
• 一个有效的 OpenAI API Key（需开通 Realtime API 权限）
• 一个有效的 Twilio 账号及电话号码
• ngrok 账号（用于内网穿透，使 Twilio 能访问本地服务）

前置依赖

确保已安装以下工具：

node -v
npm -v
ngrok version

安装步骤

1. 克隆项目并安装依赖

git clone https://github.com/openai/openai-realtime-twilio-demo.git
cd openai-realtime-twilio-demo

# 安装前端依赖
cd webapp
npm install
cd ..

# 安装后端依赖
cd websocket-server
npm install
cd ..

2. 配置环境变量

复制示例配置文件并填入你的凭证：

前端配置 (webapp/.env)

cp webapp/.env.example webapp/.env
# 编辑 webapp/.env，填入 OPENAI_API_KEY 等必要变量

后端配置 (websocket-server/.env)

cp websocket-server/.env.example websocket-server/.env
# 编辑 websocket-server/.env，填入 OPENAI_API_KEY, TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN 等

注意：请确保 websocket-server/.env 中的 PUBLIC_URL 暂时留空或设为占位符，待 ngrok 启动后再更新。

3. 启动内网穿透 (ngrok)

Twilio 需要访问你的本地服务器，使用 ngrok 暴露后端端口（默认为 8081）：

ngrok http 8081

记录终端输出的 Forwarding URL（例如：https://xxxx-xxxx.ngrok-free.app），并将其填入 websocket-server/.env 的 PUBLIC_URL 变量中。

4. 启动服务

你需要打开三个独立的终端窗口分别运行以下命令：

终端 1：启动前端 (Webapp)

cd webapp
npm run dev

终端 2：启动 WebSocket 服务端

cd websocket-server
npm run dev

终端 3：保持 ngrok 运行 (已在步骤 3 启动，保持该窗口开启即可)

基本使用

1. 配置 Twilio Webhook

登录 Twilio Console，找到你购买的电话号码，将其 Voice Webhook 设置为你的 ngrok 地址加上 /twiml 路径：

https://<你的-ngrok-URL>/twiml

例如：https://54c5-35-170-32-42.ngrok-free.app/twiml

2. 发起测试呼叫

1. 在浏览器中打开前端应用（通常为 http://localhost:3000）。
2. 页面应显示已连接到后端日志服务。
3. 使用手机拨打你在 Twilio 配置的电话号码。
4. 通话接通后，你将听到 "Connected" 提示音，随后即可与 AI 进行实时语音对话。
5. 前端页面将实时显示通话转录内容。

3. 功能说明

• 实时交互：说话时 AI 会实时响应，延迟极低。
• 函数调用模拟：当前演示包含模拟的函数调用逻辑，实际生产中可在此处接入真实业务代码。

安全提示：本项目为演示用途，未经过严格的安全加固。在生产环境部署前，请务必进行安全审计并完善鉴权机制。