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:

ParameterTypeRequiredValue
deviceIdStringYes

SHA1 (AppId + AccessToken), where AppId and AccessToken are also used for OAuth authentication.

instanceIdStringYesA 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 (smile)

Error

HTTP CodeNotes
401 Not AuthorizedAuthentication could not be performed.

WebSocket messages

Message format

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

NameTypeDescription
timestampNumberThe time when the message was sent on WebSocket, with microtimestamp precision.
classStringThe class is always an (functionality reserved for the future).
contentAPINotificationThe actual payload of the message.

The APINotification has the following format:

NameTypeDescription
fromAppString

The ID of the app that generated the message.

toTypeString

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)
toDestString

The ID of the destination:

  • <UserID> - valid for toType=user only
  • <OrgID> - valid for toType=org only
dateNumber

The date when the message was generated, timestamp.

contextStringA context for the APINotification.
eventStringThe event in the context space.
nonceStringAn arbitrary string generated by the producer of the notification.
payloadJSON ObjectA 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.

NameTypeDesc
phoneCallIdObject-IdThe ID of the phoneCall.
phoneCallViewIdObject-IdThe ID of the vnode that was changed.
extensionJSON Object

The extension is always relative to the phoneCallView. The following properties are available:

  • extensionId
  • number
  • extendedNumber
  • DID (if incoming call, the DID called)
statusString

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)
recordedString

The status of the call recording:

  • on - the call is recorded
  • off - the call is no longer recorded
appString
  • voicemail - the voicemail is running on this call leg
  • fax - the fax is running on this call leg
holdString
  • on - the call leg is placed on hold
  • off - the call leg is placed off hold
parkedString
  • on - the call leg is in parking
  • off - the call leg is out of parking
flowString

The flow of the call relative to extension can be:

  • incoming
  • outgoing
calleridString

This is set up only for incoming calls.

dialedStringThis 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
answeredDateWhen the call was answered.
startedDateWhen the call was started in the system.
nonceStringA 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.