Setting up event listener

The nguc-api support the ability for clients to be notified when the state of its users, devices, queues and calls etc changes. The events are sent out by the nguc-event pusher api using websockets.

The event pusher uses an implementation of the SockJS protocol. Details for the SockJS protocol can be found at.

To start receiving events you have to to connect a websocket to the following endpoint.


wss://event-nguc.weblink.se/id1/id2/websocket

The parameters id1 and id2 are two randomly generated strings which together are unique to your connection. id1 is a 3 digit numerical value ex 123 while id2 is a randomly generated series of letters and or numbers recommended to be between 10 and 40 characters long.

One way to generate these id's using php is

rand(100, 999) . "/" . substr(md5(microtime()), 0, 8,)

Once connected the api will send out a single "o" which indicates that you need to authenticate before receiving any further information. If you don't authenticate within a few seconds you will be disconnected. You authenticate by sending an authentication request to the server containing an active OAuth2 access_token that is generated by following the steps described in the guide How to authenticate . When you refresh the access_token you must also issue a new authentication request using the new access_token.

The format of the authenticate request is as follows. Note that the presence of the escaped quotation marks is important for the server to correctly process your request.

["[\"authenticate\",{\"authorization\":\"Bearer <access_token>\"}]"]

If the authentication fail the server will respond with a "c[]" packet containing an error code and possibly a description. On the other hand if authentication succeeds then the server will start sending out change events as well as an occasional heartbeat event represented by a single "h" character. The server will send out events related to anything you have been granted access to. It is up to the client to filter what information it deems useful. All events will be wrapped inside a json array in the format below. Only status changes generates events so you will have to query the initial user/component state using the nguc rest api. 

a[ "[\"Event 1 name\", {event 1 data }], [\"Event 2 name\", { event 2 data} \"]" ]
Event protocol symbol definition
  • o - Indicates that the client needs to authenticate.
  • c[ - Indicates that authentication failed.
  • a[ - Event received
  • h - is a heartbeat event sent out approximately every 25 seconds.