Version 22.3

PortSIP PBX exposes a set of Pub/Sub topics and structured message keys that allow external systems to receive real-time updates.

global_extension_management_events

System Administrators can subscribe to the global_extension_management_events topic to receive instant notifications whenever an extension is created, updated, or deleted for all tenants.

Permission

PBX System Administrators with one of the following permissions are allowed to subscribe to this event:

System Tenant: View Only

extension_management_events

Tenant users can subscribe to the extension_management_events topic to receive instant notifications whenever an extension is created, updated, or deleted within a tenant.

Permission

Tenant users with one of the following permissions are allowed to subscribe to this event:

User: View Only

Message Keys

Each published message includes the following keys:

event_type Specifies the type of event. Possible values include:
- extension_created
- extension_updated
- extension_destroyed
extension_number The extension’s number.
disp_name The display name associated with the extension.
email The email address assigned to the extension.
extension_id The unique ID of the extension.
tenant_id The ID of the tenant to which the extension belongs.
username The username associated with the extension.
department (optional) The department of extension. If no department is configured, this key will not appear in the JSON payload.

{
  "event_type": "extension_created",
  "extension_number": "1001",
  "disp_name": "Jason Wek",
  "email": "[email protected]",
  "extension_id": "823634238409396",
  "tenant_id": "883634229655633920",
  "username": "testuser1",
  "username": "testuser1",
  "enabled": true
  }

The extension_updated event includes the same information as the extnesion_created event.

global_extension_events

System Administrators can subscribe to global_extension_events topic to receive all extension-related event messages for all tenants. This topic provides real-time updates on an extension’s registration state and availability.

Permission

System Administrators with one of the following permissions are allowed to subscribe to this event:

System Tenant: View Only

extension_events

All extension-related event messages within a tenant are published under the extension_events topic. This topic provides real-time updates on an extension’s registration state and availability.

Permission

Tenant users with one of the following permissions are allowed to subscribe to this event:

Users: View Only
PhoneSystem: View Only

The event_type key identifies the specific message type, as described below.

extension_status

The extension_status message is published in the following scenarios:

After a successful subscription When the client successfully subscribes to a specific extension, the PBX immediately returns the current status of that extension.
When the extension comes online A notification is sent when the subscribed extension registers successfully or becomes reachable.
When the extension goes offline A notification is sent when the subscribed extension unregisters or becomes unreachable.

{
  "event_type": "extension_status",
  "status": [
    {
      "extension": "sip:[email protected]",
      "extension_id": "794493219508322304",
      "call_status": "ON_ACLL",
      "online": false,
      "presence" : "AWAY",
      "presence_note": "",
      "push_online": false,
      "time": "1704186780"
    },
    {
      "extension": "sip:[email protected]",
      "extension_id": "794493219718037504",
      "call_status": "ON_CALL",
      "online": false,
      "presence" : "ONLINE",
      "presence_note": "",
      "push_online": false,
      "time": "1704186780"
    }
  ],
  "tenant_id": "794493068765036544"
}

The message is delivered in JSON format and contains the following fields:

event_type Identifies the type of extension event.
tenant_id The ID of the tenant to which the extension belongs.
status A JSON array containing the status details of the extension. Each entry includes:
- extension The SIP URI of the extension.
- presence The presence status of the extension. Possible values include: ONLINE, LUNCH, BUSINESS_TRIP, DO_NOT_DISTURB, AWAY.
- presence_note Optional text providing additional presence information.
- call_status Indicates the extension’s current call state:
  - ON_CALL — The extension is currently in an active call.
  - RINGING — The extension is currently receiving an incoming call.
  - (empty) — The extension is not involved in any call.
- online Indicates whether the extension is currently registered to the PBX.
- push_online Indicates whether push notifications are active for the extension. This field is only meaningful when online = false.
- extension_id The unique ID of the extension.
- time The timestamp of the event, represented in UNIX time.

extension_call

The extension_call message is published in the following scenarios:

When an extension initiates an outbound call Triggered as soon as the extension begins dialing.
When an extension receives an inbound call Published when the extension is being called and starts ringing.
When an extension disconnects a call Generated when the extension ends or terminates an active call.

{
  "event_type": "extension_call",
  "extension": "sip:[email protected]",
  "call_status": "ON_CALL",
  "tenant_id": "792406615960584192",
  "extension_id": "792406615960584220",
  "time": "1703690276"
}

The message is delivered in JSON format and contains the following fields:

event_type Identifies the specific type of call-related event.
extension The SIP URI of the extension associated with this event.
call_status Indicates the current call state of the extension:
- ON_CALL — The extension is actively engaged in a call.
- RINGING — The extension is receiving an incoming call.
- (empty) — The extension is not involved in any call.
tenant_id The ID of the tenant to which the extension belongs.
extension_id The unique ID of the extension.
time The timestamp of the event, represented in UNIX time.

extension_presence

The extension_presence message is published in the following scenario:

When an extension updates its presence status Triggered whenever the extension’s presence state changes—for example, switching to Do Not Disturb, Away, or any other presence mode.

{
  "event_type": "extension_presence",
  "extension": "sip:[email protected]",
  "presence": "AVAILABLE",
  "presence_note": "Driving",
  "tenant_id": "792406615960584192",
  "extension_id": "792406615960584220",
  "time": "1703690547"
}

The message is delivered in JSON format and includes the following fields:

event_type Identifies the type of presence-related event.
extension The SIP URI of the extension whose presence has changed.
presence The current presence status of the extension. Possible values include:
- ONLINE
- LUNCH
- BUSINESS_TRIP
- DO_NOT_DISTURB
- AWAY
presence_note Optional text providing additional presence information.
tenant_id The ID of the tenant to which the extension belongs.
extension_id The unique ID of the extension.
time The timestamp of the event, represented in UNIX time.

extension_agent_status

When an extension that serves as a queue agent changes its status in any queue to which the subscriber is subscribed, the PBX publishes an extension_agent_status message. This notification is triggered whenever the agent’s state changes within any of the queues they are associated with.

{
  "agent_status": [
    {
      "queue_number": "8002",
      "status": "READY"
    }
  ],
  "event_type": "extension_agent_status",
  "extension": "sip:[email protected]",
  "extension_id": "806406815892897792",
  "tenant_id": "806406773714976768",
  "time": "1707028116"
}

The message is delivered in JSON format and includes the following fields:

event_type Indicates the type of agent-related event.
extension The SIP URI of the extension (agent).
tenant_id The ID of the tenant to which the extension belongs.
extension_id The unique ID of the extension.
time The timestamp of the event, represented in UNIX time.
agent_status A JSON array containing the agent’s status for each queue they belong to. Each entry includes:
- queue_number The extension number of the queue.
- status The agent’s current status within that queue.

global_cdr_events

System Administrators can subscribe to global_cdr_events topic to receive real-time Call Detail Record (CDR) notifications for all calls for all tenants. Once a subscription is established, the PBX pushes call lifecycle updates and final CDR data to the subscriber.

Permission

System Administrators with one of the following permissions are allowed to subscribe to this event:

System Tenant: View Only

cdr_events

The cdr_events topic delivers real-time Call Detail Record (CDR) notifications for all calls within a tenant. Once a subscription is established, the PBX pushes call lifecycle updates and final CDR data to the subscriber.

Permission

Tenant users with one of the following permissions are allowed to subscribe to this event:

Analytics: View Only
Analytics: Full Access

The following message types are published under this topic:

call_start Triggered when an extension receives an incoming call. The initial call information is packaged into a JSON object and delivered to the subscriber.
call_update_info Published when call-related information changes (such as call state or routing updates). The updated call information is packaged into a JSON object and pushed to the subscriber.
call_cdr Sent immediately after a call ends. The final CDR (Call Detail Record) is packaged into a JSON object and delivered to the subscriber.

For a detailed explanation of the CDR JSON structure, please refer to the Event Reference section.

global_queue_management_events

System Administrators are authorized to subscribe to the global_queue_management_events topic for all tenants. After successfully subscribing, the PBX immediately pushes all existing queue information to the subscriber. Thereafter, any time a queue is created, updated, or deleted, the PBX sends real-time notifications with the corresponding queue details.

Permission

System Administrators with one of the following permissions are allowed to subscribe to this event:

System Tenant: View Only

queue_management_events

Tenant users are authorized to subscribe to the queue_management_events topic. After successfully subscribing, the PBX immediately pushes all existing queue information to the subscriber. Thereafter, any time a queue is created, updated, or deleted, the PBX sends real-time notifications with the corresponding queue details.

Permission

Tenant users with one of the following permissions are allowed to subscribe to this event:

Analytics: View Only

Message Keys

event_type Identifies the queue-related event type. Possible values:
- queue_created
- queue_updated
- queue_destroy
queue_number The extension number assigned to the queue.
tenant_id The ID of the tenant that owns the queue.

{
  "event_type": "queue_created",
  "queue_number": "8800",
  "tenant_id": "883634229655633920"
}

global_queue_events

The global_queue_events topic delivers real-time updates whenever a queue’s status changes for all tenants. For example, if a caller waiting in the queue hangs up, or if an agent answers a queued call, the PBX immediately pushes the updated queue status to all subscribers.

Permission

System Administrators with one of the following permissions are allowed to subscribe to this event:

System Tenant: View Only

queue_events

The queue_events topic delivers real-time updates whenever a queue’s status changes. For example, if a caller waiting in the queue hangs up, or if an agent answers a queued call, the PBX immediately pushes the updated queue status to all subscribers.

Permission

Tenant users with one of the following permissions are allowed to subscribe to this event:

Analytics: View Only

Message Keys

queue_status After a successful subscription, the PBX sends the current status of the queue—including all waiting callers and all agents assigned to the queue. Each caller entry indicates whether the caller is actively waiting or scheduled for a callback. Each agent entry includes the agent’s current state, which may be one of the following:
- Ready The agent is available to receive ACD calls.
- Queue Call The agent is currently handling an ACD (queue) call.
- Wrap Up The agent is in After Call Work (ACW).
- Other Call The agent is on a non-ACD call.
- Not Ready The agent is not available to receive ACD calls.
- Online The agent has logged out of the queue.
- Offline The agent is offline from the PBX.

{
   "event_type":"queue_status",
   "tenant_id":"676398719834259456",
   "queue_id":"677046776364007424",
   "queue_number":"8001",
   "queue_name":"Sales Department",
   "waiting_list":[
      {
         "position": "2",
         "session_id": "6763987198342",
         "caller_number" : "123456",
         "caller_name":"Thomas Young",
         "timestamp":"1676206249",
         "type" : "normal/callback"
      }，
   "agents":[
      {
         "state":"QUEUE_CALL",
         "agent_extension_number" : "101",
         "session_id" : "677046776364007",
         "caller_number" : "123456",
         "caller_name":"Thomas Young",
         "timestamp":"1676206249"
      }
   ]
   ]
}

queue_caller_status The queue_caller_status event is published whenever the list of waiting callers in a queue changes.
This message is delivered in JSON format and is triggered for any of the following reasons:
- enqueue The caller has just entered the queue and is now on the waiting list.
- agent_answered The caller has exited the queue because an agent answered the call.
- overflow The caller has reached the configured maximum waiting time and was routed to the queue’s overflow destination.
- hangup The caller hung up while waiting in the queue.
- callback The caller successfully scheduled a callback request.

{
   "event_type":"queue_caller_status",
   "tenant_id":"676398719834259456",
   "queue_id":"677046776364007424",
   "updated_callers":[
      {
         "position": "2",
         "session_id": "6763987198342",
         "caller_number" : "123456",
         "reason" : "enqueue/agent_answered/overflow/hangup/callback",
         "timestamp":"1676206249",
         "type" : "normal/callback"
      }
   ]
}

queue_agent_status The queue_agent_status key provides real-time updates about agents assigned to a queue. Whenever an agent’s status changes, a new agent is added to the queue, or an existing agent is removed, the PBX publishes an updated queue_agent_status list in JSON format to all subscribers.
The queue_agent_status list contains the current agent status entries for the queue.
In addition, the removed_agents field lists any agents that were newly removed from the queue since the previous update.

{
   "event_type" : "queue_agent_status",
   "queue_id" : "677046776364007424",
   "tenant_id" : "676398719834259456",
   "updated_agents":[
      {
         "state":"QUEUE_CALL",
         "agent_extension_number" : "101",
         "session_id" : "677046776364007",
         "caller_number" : "123456",
         "caller_name":"Thomas Young",
         "timestamp":"1676206249"
      }
   ],
   "removed_agents":[
      {
         "agent_extension_number" : "102"
      }
      ]
}

queue_sla_breached The queue_sla_breached key indicates that a caller has waited in the queue long enough to exceed the configured Service Level Agreement (SLA). When an SLA breach occurs, the PBX sends a JSON-formatted notification to all subscribers, informing them that the queue’s SLA threshold has been violated.

{
   "event_type" : "queue_sla_breached",
   "queue_id" : "677046776364007424",
   "tenant_id" : "676398719834259456",
   "caller" : "00431334081002",
   "total_callers_breached" : 6,
   "sla_time_secs" : 90,
   "waiting_callers" : 100,
   "timestamp":"1676206249"
}

Authentication

Once connected to the WSI server, use the following JSON message to authenticate:

PBX System Administrator Authentication

{
"command":"auth",
"username":"admin",
"password":"A1s2d3f4"
}

The system administrator can currently subscribe only to extension management events. To subscribe to other events, a Tenant Admin or Queue Manager is required.

Tenant User Authentication

Tenant administrators, users(extensions) can authenticate using either username/password or extension number/extension password.

Authenticate with Username

{
"command":"auth",
"username":"testuser1",
"password":"A1s2d3f4",
"domain" : "test.io"
}

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

Authenticate with Extension Number

You can authenticate using the SIP extension number and its corresponding password as well.

{
"command":"auth",
"extension_number":"101",
"password":"A1s2d3f4",
"domain" : "test.io"
}

If there is no error, the response is as follows:

{
  "command": "auth",
  "id": "1",
  "status": 0
}

Otherwise, the response includes errors as below:

{
  "command": "auth",
  "error": "access_token , username , domain or password error",
  "id": "2",
  "status": -1
}

After successful authentication, the user can subscribe to events.

To subscribe to Call Detail Record (CDR) events, send the following command. Once subscribed, all CDRs for the tenant the subscriber belongs to will be pushed to the subscriber. Only the Tenant Administrator has permission to subscribe.

{
   "command":"subscribe",
   "topics":[
      "cdr_events"
   ]
}

The System Administrator can subscribe to the global CDR event to receive CDR events from multiple tenants. To subscribe to the global CDR event for specific tenants, send the following command.

The "tenants" array should use the tenant's ID in string format as the elements.

{
   "command":"subscribe",
   "topics":[
      "global_cdr_events"
   ],
  "tenants":[
      "23435",
      "74235345"
   ]
}

To subscribe to events for specific extensions, send the following command.

The "extensions" array should use the extension number as the elements.

{
   "command":"subscribe",
   "topics":[
      "extension_events"
   ],
   "extensions":[
      "102",
      "103"
   ]
}

The PBX administrators can subscribe to this event by specifying the tenant IDs as a JSON array.

The "tenants" array should use the tenant's ID in string format as the elements.

{
   "command":"subscribe",
   "topics":[
      "global_extension_events"
   ],
   "tenants":[
      "23435",
      "74235345"
   ]
}

PBX System Administrators can subscribe to extension management events by specifying the tenant IDs as a JSON array.

The "tenants" array should use the tenant's ID in string format as the elements.

{
   "command":"subscribe",
   "topics":[
      "global_extension_management_events"
   ],
   "tenants": [
   "12345",
   "235346"
   ]
}

Subscription Limitations

Extension-Specific Subscriptions: Extensions can only subscribe to queues that they belong to or manage. If an extension is not an agent or queue manager of a queue, it cannot subscribe to that queue's events.
Tenant Admin and Queue Manager Permissions: Tenant Admin and Queue Manager users have the permission to subscribe to any queue wiin a tenant.

If extension 101 is an agent or queue manager of queues 8001 and 8002, and it subscribes to queue events using the following command.

The "queues" array should use the queue number as the elements.

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

Only the PBX administrators can subscribe to this event.

The "tenants" array should use the tenant's ID in string format as the elements.

{
   "command":"subscribe",
   "topics":[
      "global_queue_events"
   ],
   "tenants":[
      "325435",
      "534888"
   ]
}

Tenant Admin and Queue Manager users can subscribe to the queue_management_events event.

{
   "command":"subscribe",
   "topics":[
      "queue_management_events"
   ]
}

Only the PBX Administrator can subscribe to this event.

The "tenants" array should use the tenant's ID in string format as the elements.

{
   "command":"subscribe",
   "topics":[
      "global_queue_management_events"
   ],
   "tenants":[
   "325435",
   "534888"
   ]
}

Unsubscribe

To unsubscribe from all events, send the following command.

The "queues" array and "extensions" array should use the queue number, extension number as the elements.

{
   "command":"unsubscribe",
   "topics":[
      "queue_events"
   ],
   "queues":[
      "8001",
      "8002"
   ]
}

{
   "command":"unsubscribe",
   "topics":[
      "extension_events"
   ],
   "extensions":[
      "101",
      "102"
   ]
}

PreviousWSI: Pub/Sub NextVersion 22.2

Last updated 11 days ago

hashtagglobal_extension_management_events

hashtagPermission

hashtagextension_management_events

hashtagPermission

hashtagMessage Keys

hashtagglobal_extension_events

hashtagPermission

hashtagextension_events

hashtagPermission

hashtagextension_status

hashtagextension_call

hashtagextension_presence

hashtagextension_agent_status

hashtagglobal_cdr_events

hashtagPermission

hashtagcdr_events

hashtagPermission

hashtagglobal_queue_management_events

hashtagPermission

hashtagqueue_management_events

hashtagPermission

hashtagMessage Keys

hashtagglobal_queue_events

hashtagPermission

hashtagqueue_events

hashtagPermission

hashtagMessage Keys

hashtagAuthentication

hashtagPBX System Administrator Authentication

hashtagTenant User Authentication

hashtagAuthenticate with Username

hashtagAuthenticate with Extension Number

hashtagSubscribe and Unsubscribe

hashtagSubscribe to CDR Event

hashtagSubscribe to Global CDR Event

hashtagSubscribe to Extension Event

hashtagSubscribe to Global Extension Event

hashtagSubscribe to Global Extension Management Event

hashtagSubscribe Queue Event

hashtagSubscription Limitations

hashtagSubscribe Global Queue Event

hashtagSubscribe to Queue Management Event

hashtagSubscribe to Global Queue Management Event

hashtagUnsubscribe

global_extension_management_events

Permission

extension_management_events

Permission

Message Keys

global_extension_events

Permission

extension_events

Permission

extension_status

extension_call

extension_presence

extension_agent_status

global_cdr_events

Permission

cdr_events

Permission

global_queue_management_events

Permission

queue_management_events

Permission

Message Keys

global_queue_events

Permission

queue_events

Permission

Message Keys

Authentication

PBX System Administrator Authentication

Tenant User Authentication

Authenticate with Username

Authenticate with Extension Number

Subscribe and Unsubscribe

Subscribe to CDR Event

Subscribe to Global CDR Event

Subscribe to Extension Event

Subscribe to Global Extension Event

Subscribe to Global Extension Management Event

Subscribe Queue Event

Subscription Limitations

Subscribe Global Queue Event

Subscribe to Queue Management Event

Subscribe to Global Queue Management Event

Unsubscribe