如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

电话接入与 SIP

通过 SIP 将电话通话接入 OpenAI。

选择您使用的 API,查看相应的连接步骤和会话事件。

通过 SIP 中继,您可以将来电和外呼接入 GPT-Live。服务提供商与 OpenAI 收发通话音频,您的后端负责配置会话、控制通话和执行业务逻辑。SIP 信令使用 TLS,GPT-Live 要求使用 SRTP 传输通话音频。

  • 处理来电:接收来电 webhook,然后接受或拒绝呼叫。
  • 拨打电话:创建会话,通过服务提供商拨打电话号码。外呼不需要来电 webhook,也不需要发送接受呼叫的请求。

当后端需要接收会话事件或发送指令时,请使用旁路连接。旁路连接接入已有对话,音频仍由 SIP 传输。每项操作只交给一个处理程序执行,以免 webhook 重复投递或多个连接收到同一事件时重复调用工具。

处理来电

将 SIP 服务提供商收到的来电路由到您的 OpenAI 项目。每次有来电时,您的后端都会收到 webhook,并决定是否接受该呼叫。

配置电话号码和 SIP 中继

使用 Twilio 等 SIP 中继服务提供商将电话号码接入 GPT-Live。向服务提供商购买号码后,请按以下步骤配置:

  1. 在 OpenAI 设置中打开您的项目。在 Webhook 下创建一个 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 收到发往您项目的来电时,会向您的 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/28
    • 20.204.17.112/28
    • 23.98.140.64/28
    • 40.67.149.176/28
    • 40.83.204.240/28

GPT-Live 后续步骤