使用 WebSocket 监控事件

要实时监控 PBX 事件,第三方应用需要与 PBX 建立 WebSocket 连接,并订阅相关事件。本文介绍建立 WebSocket 连接、订阅事件的相关请求命令,以实现即时的 PBX 事件监控。

使用前提

需要一个有效的访问 token 来建立 WebSocket 连接。
注: 可使用 获取访问 Token刷新访问 Token 接口获得一个新的访问 token。

建立 WebSocket 连接

首先,你需要发送一个请求 URL,请求建立 WebSocket 连接。
请求 URL
要开启一个 WebSocket 连接,你需要根据 PBX 的访问设置,在请求 URL 中使用一个特殊的协议 wswss
  • 如果 PBX 使用 HTTP 访问协议,使用以下请求 URL:
    ws://{pbx_ip}:{http_port}/{api_path}/subscribe?access_token={access_token}
  • 如果 PBX 使用 HTTPS 访问协议,使用以下请求 URL:
    wss://{pbx_ip}:{https_port}/{api_path}/subscribe?access_token={access_token}
  • 如果使用 FQDN 进行远程 API 访问,使用以下请求 URL:
    wss://{pbx_fqdn_domain}
    注: 要使用 Yeastar FQDN 进行远程 API 访问,你需要配置 API 远程访问功能。更多信息,请参见 通过 Yeastar FQDN 远程访问 API
示例
请求
wss://192.168.5.150:8088/openapi/v1.0/subscribe?access_token=QJZDwxIAXBoVrUmeyLiHS3zQXrdynAmh

订阅事件

建立 WebSocket 连接后,你需要编辑并发送事件订阅信息。这样一来,PBX 将在事件发生时自动向第三方应用发送订阅的事件报告。

请求信息
可在 API 事件报告概览 中查询想要订阅的事件 ID,并根据以下格式编辑和发送事件订阅信息:
{"topic_list":[eventid1,eventid2,...]}
示例
请求
订阅 通话状态变更新通话记录 事件。
{"topic_list":[30011,30012]}
响应
{
    "errcode": 0,
    "errmsg": "SUCCESS"
}
在通话状态发生变更,或通话结束时,PBX 会主动向第三方应用发送事件报告。

保持 WebSocket 连接

出于安全目的,如果 60 秒内第三方应用和 PBX 之间无任何数据交互,WebSocket 连接将被断开。

如果你想维持长久的 WebSocket 连接,可使用 heartbeat 请求保持连接的有效性。
请求信息
heartbeat
示例
请求
heartbeat
响应
heartbeat response