VoipNow API Notifications

This page describes how you can retrieve information in real time about the phone calls placed on the VoipNow infrastructure, without having to pool UnifiedAPI services.

Overview

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:

GET /hubgetsb/ws/<Query-Parameters> HTTP/1.1

The request headers must contain WebSocket and upgrade information:

Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: <generated>
Sec-WebSocket-Protocol: notification
Sec-WebSocket-Version: 13

For more information about Sec-WebSocket-Key, please refer to RFC 6455.

Parameters

The <Query-Parameters> must contain the following:

Parameter	Type	Required	Value
deviceId	String	Yes	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.

Result

Success

Returns a standard response as shown below:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: 654c50002ca653b033e941a031e0336d
Sec-WebSocket-Protocol: notification

and upgrades the connection to WebSocket. Let the fun begin

Error

HTTP Code	Notes
401 Not Authorized	Authentication could not be performed.

WebSocket messages

Message format

All messages received on the WebSocket have the following JSON format:

Name	Type	Description
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:

Name	Type	Description
fromApp	String	The ID of the app that generated the message.
toType	String	There are two types of customers: user - message is targeted to a user only org - message is targeted to all users in an organization (broadcast)
toDest	String	The ID of the destination: <UserID> - valid for toType=user only <OrgID> - valid for toType=org only
date	Number	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:

context=sys.phonecall
event=update

The Phone Call payload has the following format.

Name	Type	Desc
phoneCallId	Object-Id	The ID of the phoneCall.
phoneCallViewId	Object-Id	The ID of the vnode that was changed.
extension	JSON Object	The extension is always relative to the phoneCallView. The following properties are available: extensionId number extendedNumber DID (if incoming call, the DID called)
status	String	The status of the call leg: created - the call leg is created destroyed - the call leg is destroyed updated - the call leg was updated (all other cases)
recorded	String	The status of the call recording: on - the call is recorded off - the call is no longer recorded
app	String	voicemail - the voicemail is running on this call leg fax - the fax is running on this call leg
hold	String	on - the call leg is placed on hold off - the call leg is placed off hold
parked	String	on - the call leg is in parking off - the call leg is out of parking
flow	String	The flow of the call relative to extension can be: incoming outgoing
callerid	String	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.
disposition		The call disposition can be any of the following: ANSWERED BUSY FAILED NO ANSWER UNKNOWN NOT ALLOWED
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

Updates

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.

WebSockets

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.

Guarantees

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.

Show all results

Page tree