Realtime API 允许客户端通过 WebRTC 或 SIP 直接连接到 API 服务器。然而，您很可能希望将工具调用和其他业务逻辑驻留在应用服务器上，以保持这些逻辑的私密性且与客户端无关。
通过“边带”控制通道进行连接，在服务器端安全地保留工具调用、业务逻辑和其他细节。我们目前为 SIP 和 WebRTC 连接都提供了边带选项。
边带连接意味着对同一个 Realtime 会话存在两个活跃连接：一个来自用户客户端，另一个来自您的应用服务器。该服务器连接可用于监控会话、更新指令以及响应工具调用。
With WebRTC
- 当 建立对等连接 您从 Realtime API 获取并接收 SDP 响应以配置连接。如果您使用了 WebRTC 指南中的示例代码，它看起来会像这样：
1
2
3
4
5
6
7
8
9
const baseUrl = "https://api.openai.com/v1/realtime/calls";
const sdpResponse = await fetch(baseUrl, {
method: "POST",
body: offer.sdp,
headers: {
Authorization: `Bearer ${EPHEMERAL_KEY}`,
"Content-Type": "application/sdp",
},
});- 获取响应将包含一个
Location标头，其中包含一个唯一的呼叫 ID，可用于在服务器上建立连接到同一 Realtime 会话的 WebSocket 连接。
1
2
3
4
// Location: /v1/realtime/calls/rtc_123456
const location = sdpResponse.headers.get("Location");
const callId = location?.split("/").pop();
console.log(callId);- 在服务器上，您随后可以 监听事件并配置会话 就像您在典型的 Realtime API WebSocket 连接中所做的那样，将该呼叫 ID 与 URL 结合使用
wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx，如下所示：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import WebSocket from "ws";
const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";
// Connect to a WebSocket for the in-progress call
const url = "wss://api.openai.com/v1/realtime?call_id=" + callId;
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.OPENAI_API_KEY,
},
});
ws.on("open", function open() {
console.log("Connected to server.");
// Send client events over the WebSocket once connected
ws.send(
JSON.stringify({
type: "session.update",
session: {
type: "realtime",
instructions: "Be extra nice today!",
},
})
);
});
// Listen for and parse server events
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.toString()));
});通过这种方式，您能够在服务器上添加工具、监控会话并执行业务逻辑，而无需在客户端上配置这些操作。
With SIP
- 用户通过 SIP 经由电话连接到 OpenAI。
- OpenAI 向您的应用服务器 webhook URL 发送 webhook，通知您的应用该会话的状态。该 webhook 看起来会像这样：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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"}
]
}
}- 应用服务器使用
call_idwebhook 中提供的值，通过类似这样的 URL 打开与 Realtime API 的 WebSocket 连接：wss://api.openai.com/v1/realtime?call_id={callId}。WebSocket 连接将在 SIP 通话期间一直保持。
随后可使用该 WebSocket 连接发送和接收事件来控制呼叫，就像会话是由 WebSocket 连接发起时您所做的那样。这包括监控呼叫、动态更新指令以及响应工具调用。