選擇你使用的 API,查看連線步驟與工作階段事件。
透過 SIP 中繼線,讓 GPT-Live 接聽來電或撥打電話。服務供應商與 OpenAI 交換通話音訊,後端則負責設定工作階段、控制通話及執行業務邏輯。SIP 信令使用 TLS,而 GPT-Live 要求以 SRTP 傳輸通話音訊。
如果後端需要接收工作階段事件或傳送指令,請使用側頻連線。側頻連線會連到現有對話,音訊則由 SIP 傳輸。每個動作都應交由單一處理常式負責,以免 webhook 重複送達,或多條連線收到同一事件,導致工具執行兩次。
處理來電
將 SIP 服務供應商收到的來電路由至你的 OpenAI 專案。每次有來電時,後端都會收到 webhook 通知,並決定是否接聽。
設定電話號碼與中繼線
透過 Twilio 等 SIP 中繼服務供應商,將電話號碼連到 GPT-Live。向服務供應商購買號碼後,請依照下列步驟設定:
- 在 OpenAI 設定中開啟你的專案。在 Webhooks 下建立 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 收到撥往你專案的來電時,會將 live.transport.incoming 事件傳送至你的 webhook 端點。驗證 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 時,標頭會包含用來排除重複通知的 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 的建立通話端點不支援外撥。
設定中繼線
使用支援 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 驗證時,請填入 digest。 |
transport.trunk.auth.username |
你在服務供應商端使用的 SIP 使用者名稱。 |
transport.trunk.auth.password |
你在服務供應商端使用的 SIP 密碼。 |
transport.trunk.caller_number |
要傳送給服務供應商的發話方電話號碼,採用 E.164 格式。 |
服務供應商的端點必須使用 sips:,以便透過 TLS 傳輸信令。網址中請勿包含憑證、路徑、URI 標頭或其他 URI 參數。系統會拒絕本機主機名稱,以及直接填入的私有或本機 IP 位址。請將 OpenAI API 金鑰和 SIP 憑證保存在伺服器上。
建立工作階段
傳送 POST /v1/live/sessions,並附上工作階段設定與 transport.type: "sip"。建立工作階段時,請選擇語音與委派模式。音訊格式由 SIP 協商,因此請省略 audio.format。
此範例使用 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 秒內的事件,再持續傳送新事件,因此太晚連線可能會錯過較早的通話進度。這 3 秒的重播範圍也適用於對話事件和回傳的音訊。重播的通話進度事件會保留原始事件 ID,請依 event_id 排除重複的通話進度事件。詳情請參閱連線時重播事件。
建立連線後,即可使用通話控制功能傳送按鍵音、轉接通話或掛斷電話。請保持側頻連線開啟,以接收 session.closed 和最終用量,詳情請參閱用量與正常關閉。
處理限制與錯誤
響鈴時間上限為 3 分鐘,接通後的通話時間上限為 2 小時。建立工作階段時無法透過要求調整這些限制。
若工作階段設定無效,建立要求的回應會直接指出錯誤。建立傳輸連線失敗時可能會傳回 502,初始化逾時則會傳回 504。工作階段建立成功後,請監聽 transport.failed,以偵測非同步建立通話時發生的錯誤。
管理進行中的通話
下列控制功能適用於 SIP 來電與外撥通話。
傳送與接收電話按鍵事件
來電者按鍵時,側頻連線會收到 transport.dtmf.received。若要將 DTMF 按鍵音傳送至 SIP 中繼線,請透過側頻 WebSocket 傳送 transport.dtmf.send 用戶端事件。按鍵音成功送出後,側頻連線會收到 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 標頭的值,可以是電話 URI(例如 tel:+14155550123),也可以是 SIP URI(例如 sip:agent@example.com)。後續的轉接流程由服務供應商處理。
請保持側頻連線開啟,直到 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 的設定 > 專案 > Webhooks 進行設定。
接著,使用已設定 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 建立連線後,你可以使用左側導覽列或點選下列頁面,開始開發即時應用程式。