PortSIP PBX 基于 WebSocket Pub/Sub 实时消息推送

You are here:
← All Topics

从 v12.5 开始,PortSIP PBX 开始支持基于 WebSocket 的 Pub/Sub 机制,用户可以在任何编程语言中使用 WebSocket 来订阅 PBX 的事件消息,一旦订阅的事件发生,PBX即主动推送消息到订阅者,消息采用 JSON 格式封装。

PortSIP PBX v12.5 支持订阅如下事件主题。

extension_events

所有和 extension 相关的事件信息将通过 extension_events 主题发布,包括如下消息 key。

extension_register: 分机注册到 PBX 或者从 PBX 注销。
call_hold: 通话被保留
call_unhold: 通话被恢复
call_start: 通话开始
call_established: 通话应答并建立成功
call_ended: 通话结束
call_noanswer: 通话没有被应答
call_reroute: 通话被 route 给其他的 target
call_fail: 通话失败
target_add: 开始呼叫一个被叫目标,比如一个分机 101 分别从 IP Phone 和 App 登录到 PBX,呼叫 101 的时候,IP Phone 和 App 将作为 target 分别被 add,target_add 事件将会被触发两次
target_ringing: 被叫目标开始振铃
target_noanswer: 被叫目标没有应答
target_fail: 被叫目标失败
target_ended: 被叫目标结束呼叫


cdr_events

当一个通话结束后,通话的 CDR 消息将会被 PBX 主动推送到订阅者, 消息主题为 cdr_events,消息 key 为如下。

call_cdr

queue_events

当队列状态发生改变时,相关的队列状态信息被主动推送到订阅者,消息主题为 queue_events,包括如下消息key。

queue_status

trunk_events

当 Trunk 的状态发生改变时候,比如成功注册到 Trunk, 或者注册到 Trunk 失败,或者和 Trunk 的注册丢失,链接断开,PBX 将主动推送 Trunk 状态信息给订阅者,消息主题为 trunk_events, 消息 key 如下。

trunk_connected
trunk_disconnected

订阅和取消订阅

在订阅消息之前,首先需要创建一个 WebSocket 并连接到 PortSIP PBX 的 8885 端口,并发送认证消息给 PBX,认证通过后,才能进行订阅和接收 PBX 推送的事件消息。

PortSIP PBX 允许分机用户或者租户订阅事件消息,认证请求如下。

分机用户认证

{
"command":"auth",
"extension":"101",
"domain":"test.com",
"password":"111111"
}

其中 domain 是分机所在的租户的 SIP Domian, 密码为分机用户的 Web 密码。

如果是租户进行订阅,认证请求如下。

{
"command" : "auth",
"name": "tenant name",
"password": "111111"
}

注意,如果是 admin 用户,那么 name 即为 admin,因为 admin 也具有租户身份。

如果请求成功,服务器返回的结果如下:

{"status":0}

如果请求失败,返回的结果如下述格式:

{"error":"name or password error","status":-1}

在成功进行认证后,即可进行消息订阅。

比如 分机 101 想订阅 102 和 103 的注册,通话相关事件消息,使用如下命令进行订阅即可。

{
"command":"subscribe",
"topics":[
 { 
 "topic" : "extension_events",
 "keys": ["extension_register", "call_start", "call_fail", "call_reroute", "call_noanswer", "call_hold", "call_unhold", "call_ended", "call_established", "target_add", "target_fail", "target_noanswer", "target_ringing", "target_ended"] 
 } 
],
"extensions":[
"102",
"103"] 
}

如果想同时订阅分机事件和 CDR 事件,使用如下命令。

{
"command":"subscribe",
"topics":[
 { 
 "topic" : "extension_events",
 "keys":["extension_register", "call_start", "call_fail", "call_reroute", "call_noanswer", "call_hold", "call_unhold", "call_ended", "call_established", "target_add", "target_fail", "target_noanswer", "target_ringing", "target_ended"] 
},
 { 
 "topic" : "cdr_events",
 "keys":["call_cdr"] 
 } 
],
"extensions":[
"102",
"103"]  
}

使用如下命令可以取消订阅。

{
"command":"unsubscribe",
"topics":[
 { 
 "topic" : "extension_events",
 "keys":["extension_register", "call_start", "call_fail", "call_reroute", "call_noanswer", "call_hold", "call_unhold", "call_ended", "call_established", "target_add", "target_fail", "target_noanswer", "target_ringing", "target_ended"] 
},
 { 
 "topic" : "cdr_events",
 "keys":["call_cdr"] 
 } 
],
"extensions":[
"102",
"103"]  
}

如果只想取消订阅 CDR 事件消息,使用如下命令。

{
"command":"unsubscribe",
"topics":[
 { 
 "topic" : "cdr_events",
 "keys":["call_cdr"] 
 } 
] 
}

分机用户和租户还可以订阅队列相关的消息,这样一旦队列状态发生改变,如果有新的通话入队,出队,或者出现早释通话,PBX 即可将相关队列消息推送给订阅者。

如果是分机用户订阅队列事件消息,分机必须是订阅队列的成员,或者管理员,否则系统不会推送队列相关的事件消息给订阅分机。如果租户订阅队列事件消息,则有权订阅任何队列。

{
"command":"subscribe",
"topics":[
 { 
 "topic" : "queue_events",
 "keys":["queue_status"] 
 } 
],
 "queues":[
"8001",
"8002"]  
}

如果想要订阅 TRUNK 相关的状态消息,使用如下命令。

注意,只有租户才有权限订阅 TRUNK 事件消息。

{
"command":"subscribe",
"topics":[
 { 
 "topic" : "trunk_events",
 "keys":["trunk_connected", "trunk_disconnected"] 
 } 
] 
}

一旦 TRUNK 成功连接或者连接丢失,订阅者即可收到 PBX 推送的消息通知。