The API Notifications is a REST service restricted to VoipNow apps installed on the user level. The service is not accessible to apps deployed on other account levels.
Once the connection to the service is established, the HTTP connection is upgraded to the WebSocket protocol.
Connect to service
In order to get notifications in real time, you must send a GET request to the following endpoint:
The request headers must contain WebSocket and upgrade information:
For more information about Sec-WebSocket-Key, please refer to RFC 6455.
The <Query-Parameters> must contain the following:
SHA1 (AppId + AccessToken), where AppId and AccessToken are also used for OAuth authentication.
|instanceId||String||Yes||A random string that identifies the connection context. If you want to open multiple WebSockets for the same app, use different instanceId.|
Returns a standard response as shown below:
and upgrades the connection to WebSocket. Let the fun begin
|401 Not Authorized||Authentication could not be performed.|
All messages received on the WebSocket have the following JSON format:
|timestamp||Number||The time when the message was sent on WebSocket, with microtimestamp precision.|
|class||String||The class is always an (functionality reserved for the future).|
|content||APINotification||The actual payload of the message.|
The APINotification has the following format:
The ID of the app that generated the message.
There are two types of customers:
The ID of the destination:
The date when the message was generated, timestamp.
|context||String||A context for the APINotification.|
|event||String||The event in the context space.|
|nonce||String||An arbitrary string generated by the producer of the notification.|
|payload||JSON Object||A JSON object that fully describes the API notification.|
Phone call notifications
Notifications related to phone call events can be easily recognized because the APINotification that carries them has:
The Phone Call payload has the following format.
|phoneCallId||Object-Id||The ID of the phoneCall.|
|phoneCallViewId||Object-Id||The ID of the vnode that was changed.|
The extension is always relative to the phoneCallView. The following properties are available:
The status of the call leg:
The status of the call recording:
The flow of the call relative to extension can be:
This is set up only for incoming calls.
|dialed||String||This is the phone number that was dialed and it applies only to outgoing calls.|
The call disposition can be any of the following:
|answered||Date||When the call was answered.|
|started||Date||When the call was started in the system.|
|nonce||String||A unique call identifier that can be set up by the API customers.|
Software development advice
The payload of the notification is not identical to the PhoneCall resource, but it carries enough information to allow a client to understand what happens with the call. In most common scenarios, the client does not have to interrogate UnifiedAPI in order to get the PhoneCall resource.
For example, you can easily integrate VoipNow with an app that requires to be informed whenever a user is called from a specific number in order to show an incoming call panel in real time.
The WebSocket client must be implemented using socket.io (version 1.0). While socket.io is a node project, there are compatible client implementations for other programming languages as well.
It is very important to properly handle WebSocket connect/disconnect/reconnect, otherwise notifications may be missed because API Notifications are not queued; they are sent as soon as they occured. If the client is not listening on the WebSocket, the notification is missed.
Note that API Notifications are not stateful. There is no guarantee that all properties in the payload are available.
We guarantee that there is enough information to identify the call and all properties that have been modified are present.
Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.