如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

電話通訊與 SIP

透過 SIP 將電話通話接到 OpenAI。

選擇你使用的 API,查看連線步驟與工作階段事件。

透過 SIP 中繼線,讓 GPT-Live 接聽來電或撥打電話。服務供應商與 OpenAI 交換通話音訊,後端則負責設定工作階段、控制通話及執行業務邏輯。SIP 信令使用 TLS,而 GPT-Live 要求以 SRTP 傳輸通話音訊。

  • 處理來電:收到來電 webhook 通知後,接聽或拒接來電。
  • 撥打電話:建立工作階段,透過服務供應商撥打電話號碼。外撥不需要來電 webhook,也不需要傳送接聽要求。

如果後端需要接收工作階段事件或傳送指令,請使用側頻連線。側頻連線會連到現有對話,音訊則由 SIP 傳輸。每個動作都應交由單一處理常式負責,以免 webhook 重複送達,或多條連線收到同一事件,導致工具執行兩次。

處理來電

將 SIP 服務供應商收到的來電路由至你的 OpenAI 專案。每次有來電時,後端都會收到 webhook 通知,並決定是否接聽。

設定電話號碼與中繼線

透過 Twilio 等 SIP 中繼服務供應商,將電話號碼連到 GPT-Live。向服務供應商購買號碼後,請依照下列步驟設定:

  1. 在 OpenAI 設定中開啟你的專案。在 Webhooks 下建立 webhook 端點,並訂閱 live.transport.incoming 事件。
  2. 在一般設定中找到專案 ID。專案 ID 以 proj_ 開頭,請使用上述 webhook 所屬專案的 ID。
  3. 將服務供應商的 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/28
    • 20.204.17.112/28
    • 23.98.140.64/28
    • 40.67.149.176/28
    • 40.83.204.240/28

GPT-Live 後續步驟