选择您使用的 API,查看相应的连接步骤和会话事件。
通过 SIP 中继,您可以将来电和外呼接入 GPT-Live。服务提供商与 OpenAI 收发通话音频,您的后端负责配置会话、控制通话和执行业务逻辑。SIP 信令使用 TLS,GPT-Live 要求使用 SRTP 传输通话音频。
当后端需要接收会话事件或发送指令时,请使用旁路连接。旁路连接接入已有对话,音频仍由 SIP 传输。每项操作只交给一个处理程序执行,以免 webhook 重复投递或多个连接收到同一事件时重复调用工具。
处理来电
将 SIP 服务提供商收到的来电路由到您的 OpenAI 项目。每次有来电时,您的后端都会收到 webhook,并决定是否接受该呼叫。
配置电话号码和 SIP 中继
使用 Twilio 等 SIP 中继服务提供商将电话号码接入 GPT-Live。向服务提供商购买号码后,请按以下步骤配置:
- 在 OpenAI 设置中打开您的项目。在 Webhook 下创建一个 webhook 端点,并订阅
live.transport.incoming事件。 - 在常规下查找项目 ID。项目 ID 以
proj_开头,请使用该 webhook 所属项目的 ID。 - 将服务提供商的 SIP 中继指向全球 SIP URI
sip:$PROJECT_ID@sip.api.openai.com;transport=tls,或使用以下区域端点之一:- 如需满足欧洲数据驻留要求,请使用
sip:$PROJECT_ID@sip-eu.api.openai.com;transport=tls。 - 如需将呼叫路由到位于印度境内的 SIP 主机,请使用
sip:$PROJECT_ID@sip-in.api.openai.com;transport=tls。
- 如需满足欧洲数据驻留要求,请使用
使用此流程前,请确认您的项目已启用 GPT-Live SIP 支持,并且服务提供商已将 SIP 中继路由到该项目。
接收来电
当 OpenAI 收到发往您项目的来电时,会向您的 webhook 端点发送 live.transport.incoming 事件。请验证 webhook 签名并对收到的事件去重,然后接受或拒绝呼叫。
webhook 使用 data.type: "sip" 标识 SIP 呼叫,并提供 data.session_id。对该通话执行任何 Live 操作时,都应原样使用这个会话 ID。请将 data.sip_headers 视为不可信的来电者元数据,不得将其用作授权依据。
以下是 webhook 请求体示例:
{
"object": "event",
"id": "evt_abc123",
"type": "live.transport.incoming",
"created_at": 1750287018,
"data": {
"type": "sip",
"session_id": "live_123",
"sip_headers": [
{ "name": "From", "value": "sip:+14155550123@sip.example.com" },
{ "name": "To", "value": "sip:+18005550100@sip.example.com" },
{ "name": "Call-ID", "value": "call-123@example.com" }
]
}
}created_at 字段是以秒为单位的 Unix 时间戳。投递请求头中的 webhook-id 用于去重,webhook-timestamp 记录本次投递尝试的时间,webhook-signature 用于验证签名。服务端处理程序的写法请参阅 webhook 签名验证示例。
现有集成可能仍会收到已弃用的 live.call.incoming 事件,其中没有 data.type。迁移期间,请同时处理这两个事件名称,并保留旧订阅,直到旧事件及其重试全部投递完毕。同一个待处理呼叫也可能触发 Realtime webhook。请由一个处理程序决定接受还是拒绝呼叫,避免通过两个 API 重复接受呼叫。
接受或拒绝呼叫
按照应用的授权和路由规则处理呼叫。要接受呼叫,请发送经过身份验证的 POST /v1/live/sessions/{session_id}/accept 请求,并在请求体顶层提供 session 对象:
{
"session": {
"type": "live",
"model": "gpt-live-1",
"instructions": "You are answering an inbound support call.",
"audio": { "output": { "voice": "marin" } },
"delegation": { "type": "client" }
}
}从可信后端发送呼叫控制请求时,请使用 Authorization: Bearer $OPENAI_API_KEY。接受呼叫时,请选择音色和委派模式。音频格式由 SIP 协商,因此请省略 audio.format。示例采用客户端委派,您的后端必须处理委派的任务。有关客户端委派和 Responses 委派的配置,请参阅委派与工具。
成功接受呼叫后,端点会在会话初始化完成时返回 200 OK,响应体为空。请先检查并处理 HTTP 错误,再将呼叫标记为已接受。
要拒绝呼叫,请发送 POST /v1/live/sessions/{session_id}/reject 并提供 SIP 状态码,例如用 { "status_code": 486 } 表示占线。状态码必须是 300 至 699 之间的整数(含两端)。第一个接受或拒绝呼叫的决定生效,随后尝试对同一呼叫作出决定的请求会收到 decision_already_made。
将后端接入会话
接受呼叫后,请建立旁路 WebSocket 连接,连接地址为 wss://api.openai.com/v1/live/sessions/{session_id}/attach。使用已接受呼叫的会话 ID,以及相同的项目身份验证信息和连接请求头。不要再次发送 session.start。
SIP 传输通话音频。请使用旁路连接处理转录文本、委派任务、工具调用、指令和回传音频。即使多个连接收到同一事件,每项有副作用的操作也应只由一方执行。
连接建立后,您可以使用通话控制功能发送按键音、转接通话或挂断。
拨打电话
使用创建会话端点,通过您的 SIP 服务提供商拨打电话号码。服务提供商负责连接电话网络,GPT-Live 负责与对方交谈。
所有组织都可以通过 Live API 使用 SIP 外呼功能。Realtime API 的呼叫创建端点不支持此功能。
配置 SIP 中继
使用支持 TLS 信令和 SDES-SRTP 媒体传输的中继。拨打电话前,请在服务提供商的设置中启用 SRTP。
每次请求都需提供中继配置:
| 字段 | 值 |
|---|---|
transport.destination |
要拨打的电话号码,采用 E.164 格式,例如 +14155550123。不支持使用 SIP URI 作为目的地。 |
transport.trunk.provider_url |
服务提供商的端点,例如 sips:sip.example.com:5061。默认端口为 5061,;transport=tcp 为可选参数。 |
transport.trunk.auth.type |
使用 SIP 摘要身份验证时,值为 digest。 |
transport.trunk.auth.username |
您在服务提供商处使用的 SIP 用户名。 |
transport.trunk.auth.password |
您在服务提供商处使用的 SIP 密码。 |
transport.trunk.caller_number |
发送给服务提供商的主叫号码,采用 E.164 格式。 |
服务提供商的端点必须使用 sips: 进行 TLS 信令传输。URL 中不得包含凭据、路径、URI 标头或其他 URI 参数。系统会拒绝本地主机名,也会拒绝以字面值指定的私有或本地 IP 地址。请将 OpenAI API 密钥和 SIP 凭据保存在您的服务器上。
创建会话
发送 POST /v1/live/sessions,并提供会话配置和 transport.type: "sip"。创建会话时,请选择音色和委派模式。请省略 audio.format,因为音频格式由 SIP 协商。
本示例使用 curl 和 jq。请在服务器环境中设置 OPENAI_API_KEY、SIP_USERNAME 和 SIP_PASSWORD,并将示例中的服务提供商端点和电话号码替换为您实际使用的值。示例采用客户端委派,您的后端必须处理委派的任务。
jq -n \
--arg username "$SIP_USERNAME" \
--arg password "$SIP_PASSWORD" \
'{
"session": {
"model": "gpt-live-1",
"instructions": "Help the user schedule an appointment.",
"audio": { "output": { "voice": "marin" } },
"delegation": { "type": "client" }
},
"transport": {
"type": "sip",
"destination": "+14155550123",
"trunk": {
"provider_url": "sips:sip.example.com:5061",
"auth": {
"type": "digest",
"username": $username,
"password": $password
},
"caller_number": "+14155550100"
}
}
}' | curl https://api.openai.com/v1/live/sessions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @-会话初始化完成后,请求会返回 200 OK:
{
"session": { "id": "live_123" },
"transport": { "type": "sip" }
}收到此响应并不表示对方已接听电话。响应中不包含 SDP 或中继凭据。请原样保留 session.id,用于建立旁路连接和控制通话。外呼不需要来电 webhook,也不需要发送接受呼叫的请求。
监控并结束通话
使用 OpenAI API 密钥将后端连接到 wss://api.openai.com/v1/live/sessions/{session_id}/attach。不要再次发送 session.start。旁路连接传递对话事件、委派任务和呼叫进度,SIP 传输音频。
| 事件 | 含义 |
|---|---|
transport.ringing |
服务提供商报告对方正在振铃,或已开始传输早期媒体。 |
transport.answered |
对方已接听,媒体连接已建立。 |
transport.failed |
会话初始化后,呼叫建立失败。请检查 error.code 和 error.message。 |
每个呼叫进度事件都包含 event_id 和 session_id。请在创建会话后立即接入旁路连接。旁路连接会先重放接入前 3 秒内的事件,然后持续推送新事件。如果接入过晚,您可能会错过较早的呼叫进度事件。这一重放窗口也适用于对话事件和回传音频。重放的呼叫进度事件保留原始事件 ID。请按 event_id 对这些事件去重。详情请参阅接入时的事件重放。
连接建立后,您可以使用通话控制功能发送按键音、转接通话或挂断。请保持旁路连接打开,以便接收 session.closed 事件和最终用量,详见用量与正常关闭。
处理限制和错误
振铃最长可持续 3 分钟,接通后的通话最长可持续 2 小时。创建请求不支持调整这些限制。
如果会话配置无效,创建请求会直接返回错误。传输连接建立失败时可能返回 502,初始化超时则返回 504。创建成功后,请监控 transport.failed 事件,以发现异步建立连接时出现的故障。
管理正在进行的通话
以下控制功能对 SIP 来电和外呼均适用。
发送和接收按键事件
来电者按键时,旁路连接会收到 transport.dtmf.received。要向 SIP 中继发送 DTMF 音,请通过旁路 WebSocket 发送 transport.dtmf.send 客户端事件。DTMF 音发送成功后,旁路连接会收到 transport.dtmf.sent。
如果您提供了 event_id,通知会在 client_event_id 字段中返回该值。发送失败时会返回 error 事件,其中包含 error.client_event_id。
转接或结束通话
要转接通话,请发送 POST /v1/live/sessions/{session_id}/refer,并通过 { "target_uri": "sip:agent@example.com" } 指定转接目的地。要挂断通话,请发送 POST /v1/live/sessions/{session_id}/hangup,不附带请求体。两种请求成功时均返回 200 OK,响应体为空。
转接目的地将写入 SIP Refer-To 标头,可以是 tel:+14155550123 这样的电话 URI,也可以是 sip:agent@example.com 这样的 SIP URI。服务提供商负责处理后续转接流程。
请保持旁路连接打开,直到 session.closed 事件提供最终用量。有关用量报告和会话关闭原因,请参阅用量与正常关闭。
SIP 网络要求
GPT-Live SIP 通话通过不同的网络路径传输信令和媒体。请配置网络,允许这两类流量通过:
- SIP 信令:
sip.api.openai.com和sip-eu.api.openai.com是通过 GeoIP 路由的端点。印度端点sip-in.api.openai.com将信令路由到印度境内的 SIP 主机。请允许出站 TCP/TLS 流量访问 DNS 为所选端点返回的地址,目标端口为5061。 - SRTP 媒体: API 会在协商确定的 SDP 中指定单独的媒体 IP 地址和 UDP 端口。请允许通过 UDP 与以下 CIDR 地址段双向收发 SRTP 流量:
13.79.45.80/2820.204.17.112/2823.98.140.64/2840.67.149.176/2840.83.204.240/28
GPT-Live 后续步骤
- 提示词指南:为语音智能体编写提示词。
- Webhook 与服务端控制:从后端管理会话。
- 委派与工具:将语音接入负责推理和工具调用的后端。
- 管理会话:处理转录文本、管理会话状态并关闭会话。
- 延迟与成本:了解延迟和用量。
- GPT-Live 合作伙伴集成:查找相应服务提供商的配置指南和示例。
SIP 是一种通过互联网拨打电话的协议。配合使用 SIP 和 Realtime API,您可以将来电路由到 API。
概述
要将电话号码接入 Realtime API,请使用 SIP 中继服务提供商(例如 Twilio)。这类服务会将电话通话转换为 IP 流量。向 SIP 中继服务提供商购买电话号码后,请按以下步骤操作。
首先,为来电创建一个 webhook。在 platform.openai.com 上,前往设置 > 项目 > Webhook。
然后,使用配置了该 webhook 的项目 ID,将 SIP 中继指向 OpenAI 的全球 SIP URI sip:$PROJECT_ID@sip.api.openai.com;transport=tls。如需按区域路由,请使用以下端点之一:
- 如需满足欧洲数据驻留要求,请使用
sip:$PROJECT_ID@sip-eu.api.openai.com;transport=tls。 - 如需将呼叫路由到位于印度境内的 SIP 主机,请使用
sip:$PROJECT_ID@sip-in.api.openai.com;transport=tls。
要查找 $PROJECT_ID,请前往设置 > 项目 > 常规。该页面会显示以 proj_ 开头的项目 ID。
当 OpenAI 收到与您的项目关联的 SIP 流量时,就会触发 webhook。您会收到一个 realtime.call.incoming 事件,如下例所示:
POST https://my_website.com/webhook_endpoint
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52 # unique id for idempotency
webhook-timestamp: 1750287078 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI
{
"object": "event",
"id": "evt_685343a1381c819085d44c354e1b330e",
"type": "realtime.call.incoming",
"created_at": 1750287018, // Unix timestamp
"data": {
"call_id": "some_unique_id",
"sip_headers": [
{ "name": "From", "value": "sip:+142555512112@sip.example.com" },
{ "name": "To", "value": "sip:+18005551212@sip.example.com" },
{ "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"}
]
}
}收到 webhook 后,您可以使用其中的 call_id 接受或拒绝呼叫。接受呼叫时,需要提供 Realtime API 会话所需的配置,如提示词和音色。会话建立后,您可以像往常一样建立 WebSocket 连接并监控会话。下文介绍如何通过 API 接受、拒绝、监控、转接和挂断呼叫。
接受呼叫
使用接受呼叫端点接受来电,并配置用于接听来电的实时会话。请发送与 create client secret 请求相同的参数,确保在将通话桥接到模型之前设置好实时模型、音色、工具或提示词。
curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/accept" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "realtime",
"model": "gpt-realtime-2.1",
"instructions": "You are Alex, a friendly concierge for Example Corp."
}'请求路径必须包含 call_id,其值来自 realtime.call.incoming webhook。每个请求都必须包含上例所示的 Authorization 请求头。当 SIP 侧开始振铃且实时会话正在建立时,端点会返回 200 OK。
拒绝呼叫
如果您不打算处理某个来电(例如来电号码的国家代码不受支持),请使用拒绝呼叫端点拒绝呼叫邀请。请提供 call_id 路径参数。您还可以在 JSON 请求体中提供 SIP status_code(例如用 486 表示“占线”),以控制返回给运营商的响应。
curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/reject" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status_code": 486}'如果未提供状态码,API 默认使用 603 Decline。请求成功时,OpenAI 会在送达 SIP 响应后返回 200 OK。
监控呼叫事件
接受呼叫后,请建立到同一会话的 WebSocket 连接,以流式接收事件并发送实时指令。使用 call_id 参数连接现有通话时,不会使用 model 参数,因为模型已经通过 accept 端点配置。
WebSocket 请求
GET wss://api.openai.com/v1/realtime?call_id={call_id}
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
call_id |
字符串 | 来自 realtime.call.incoming webhook 的呼叫标识符。 |
请求头
Authorization: Bearer YOUR_API_KEY
此 WebSocket 连接的行为与其他 Realtime API 连接完全相同。您可以发送 response.create 等客户端事件来控制通话,并监听服务端事件以跟踪进度。详情请参阅 Webhook 与服务端控制。
import WebSocket from "ws";
const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";
const ws = new WebSocket(`wss://api.openai.com/v1/realtime?call_id=${callId}`, {
headers: {
Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
},
});
ws.on("open", () => {
ws.send(
JSON.stringify({
type: "response.create",
})
);
});转接通话
使用呼叫转接端点转接正在进行的通话。请提供 call_id 和 target_uri。后者将写入 SIP Refer-To 标头,其值可以是 tel:+14155550123 或 sip:agent@example.com。
curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/refer" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target_uri": "tel:+14155550123"}'OpenAI 将 REFER 请求转发给您的 SIP 服务提供商后,会返回 200 OK。之后由下游系统为来电者处理余下的通话流程。
挂断通话
当您的应用需要断开与来电者的连接时,请使用挂断端点结束会话。此端点可用于终止 SIP 和 WebRTC 实时会话。
curl -X POST "https://api.openai.com/v1/realtime/calls/$CALL_ID/hangup" \
-H "Authorization: Bearer $OPENAI_API_KEY"API 开始断开通话连接时,会返回 200 OK。
SIP 信令和媒体的 IP 地址范围
Realtime SIP 通话通过不同的网络路径传输信令和媒体。为确保通话正常进行,请按以下说明配置网络,允许信令和媒体流量通过。
SIP 信令
sip.api.openai.com 和 sip-eu.api.openai.com 是通过 GeoIP 路由的端点。印度端点 sip-in.api.openai.com 将信令路由到印度境内的 SIP 主机。您的网络必须允许出站 TCP/TLS 流量访问 DNS 为所选端点返回的地址,目标端口为 5061。
SRTP 媒体
API 会在协商确定的 SDP 中指定单独的媒体 IP 地址和 UDP 端口。您的网络必须允许通过 UDP 与以下 CIDR 地址段双向收发 SRTP 流量:
13.79.45.80/2820.204.17.112/2823.98.140.64/2840.67.149.176/2840.83.204.240/28
服务端示例
下面是 realtime.call.incoming 事件处理程序的示例。它先接受呼叫,然后将 Realtime API 发出的所有事件写入日志。
如果使用 Ruby 示例,请先设置 OPENAI_API_KEY 和 OPENAI_WEBHOOK_SECRET 环境变量,然后运行 gem install openai webrick async-websocket 安装所需依赖。
from flask import Flask, request, Response, jsonify, make_response
from openai import OpenAI, InvalidWebhookSignatureError
import asyncio
import json
import os
import requests
import time
import threading
import websockets
app = Flask(__name__)
client = OpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])
AUTH_HEADER = {"Authorization": "Bearer " + os.environ["OPENAI_API_KEY"]}
call_accept = {
"type": "realtime",
"instructions": "You are a support agent.",
"model": "gpt-realtime-2.1",
}
response_create = {
"type": "response.create",
"response": {
"instructions": ("Say to the user 'Thank you for calling, how can I help you'")
},
}
async def websocket_task(call_id):
try:
async with websockets.connect(
"wss://api.openai.com/v1/realtime?call_id=" + call_id,
additional_headers=AUTH_HEADER,
) as websocket:
await websocket.send(json.dumps(response_create))
while True:
response = await websocket.recv()
print(f"Received from WebSocket: {response}")
except Exception as e:
print(f"WebSocket error: {e}")
@app.route("/", methods=["POST"])
def webhook():
try:
event = client.webhooks.unwrap(request.data, request.headers)
except (InvalidWebhookSignatureError, ValueError) as e:
print("Invalid signature", e)
return Response("Invalid signature", status=400)
if event.type == "realtime.call.incoming":
requests.post(
"https://api.openai.com/v1/realtime/calls/"
+ event.data.call_id
+ "/accept",
headers={**AUTH_HEADER, "Content-Type": "application/json"},
json=call_accept,
).raise_for_status()
threading.Thread(
target=lambda: asyncio.run(websocket_task(event.data.call_id)),
daemon=True,
).start()
return Response(status=200)
if __name__ == "__main__":
app.run(port=8000)后续步骤
通过 SIP 建立连接后,您可以使用左侧导航栏或访问以下页面,开始构建实时应用。