Going Real-Time with PortSIP PBX Pub/Sub

You are here:
← All Topics

From v12.5,PortSIP PBX provides the Pub/Sub mechanism which is based on the WebSocket. The user is able to create the WebSocket in any programming languages to subscribe to the PBX events, once the subscribed events occur, PortSIP PBX will push the event message to the subscriber automatically, the message is in the JSON format.

Topics and keys

PortSIP PBX v12.5 provides below topics and keys for the Pub/Sub.

extension_events

All extension related event messages will be published by extension_events . Below, are the various message keys.

  • extension_register: extension registered to the PBX or un-register from the PBX.
  • call_hold: call was held.
  • call_unhold: call has been resumed from hold.
  • call_start: call starting.
  • call_established: the call was answered and successfully connected.
  • call_ended: call has ended.
  • call_noanswer: call is a ‘no answer’.
  • call_reroute: the call was re-routed to another target.
  • call_fail: call has failed.
  • target_add: start call to a target. For example, extension 101 is registered to PBX from an IP Phone or an App, when someone makes calls to 101, the IP Phone, or App will be added as the target. (The target_add event will be triggered two times.)
  • target_ringing: the called target is ringing.
  • target_noanswer: there is no answer from the called target.
  • target_fail: call failed from the called target. For example, the App / IP Phone rejected the call.
  • target_ended: call has ended from the called target. For example, the App / IP Phone hangs up the call.

cdr_events

Once a call has ended, the CDR of this call will be pushed to the subscribers, the message topic is: cdr_events, the message key is below.

  • call_cdr: once a call has ended, the CDR will be packed in JSON format and pushed to subscriber.

queue_events

Once the queue status is changed, for example, the caller who in the queue has hung up the call, or the caller who is in the queue is answered by an agent, the related status information will be pushed to the subscribers. The message topic is queue_events. This is the message key.

  • queue_status: if the queue status changed, the information will be packed into JSON message and pushed to subscriber.
  • queue_member_state: if the agent of the queue state is set to ready or not-ready, this message will be pushed.

trunk_events

Once a trunk state is changed, for example, the PBX successfully registered to a Trunk, or register to the Trunk fails, or the registration is lost from a trunk, or a connection timeout, PortSIP PBX will push the message information to the subscribers, the message topic is trunk_events, the keys are below.

  • trunk_connected: PBX is successfully connected to a trunk.
  • trunk_disconnected: PBX is successfully connected to a trunk.

Subscribe and unsubscribe

In order to subscribe the events, a user needs to establish a session by opening a WebSocket connection to the listening port (8885) of the PortSIP PBX with authentication credentials. This requires a previously established user account on the PortSIP PBX. User account can be an extension or a tenant.

You can use below JSON message to do the authorazation:

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

The domain is the SIP domain of the extension, the password is the web password of extension.

If the tenant wishes to subscribe to the events, authorization is required as below:

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

If there no error, the response is as below:

{"status":0}

Otherwise the response including error as below:

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

After successfully being authenticated, the user can now subscribe to the events.

For instance, the extension 101 wishes to subscribe to extension 102, 103 events, just send the below command to subscribe.


{
"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"] 
}

If we want to subscribe both extension events and CDR events, use the below command.

{
"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"]  
}

If we want to unsubscribe the events, use the below command.

{
"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"]  
}

If we just want to unsubscribe the CDR events, use the below command.

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

If we want to subscribe to the queue status, use the below command.

Note, the extension only have permission to subscribe to the queues belonging to that extension, if the extension(subscriber) is not a member of the queue, and also not a queue manager of the queue, the events will not push to the extension(subscriber). For example, if extension 101 is the member/agent/queue manager of queue 8001 and 8002, after 101 is subscribed to queue events, both 8001 and 8002 queue status will be pushed to extension 101.

The tenant has permissions to subscribe any queues.

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

If we want to subscribe the trunk events, use the below commands.

Note: only the tenant has the permissions to subscribe to the trunk events.

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

After successfully being subscribed to the trunk events, once a trunk is connected or disconnected, the PBX will push information to the subscriber.