About this Document

The silhouette Public API integrates call management, status monitoring, and provisioning, and enables applications to receive asynchronous notification of call- related events. Applications can use it to make calls, answer calls, release calls and view the call details of active calls in silhouette. It allows applications to monitor the call and presence status of specific users by subscribing to receive call and presence status events.

The silhouette API is a RESTful hyperlinking API, supporting the following the HAL media type specification, combined with a WebSocket-based stream for reporting real- time call and presence events.

                                                                                                                                                          Public API Guide

Architecture

The silhouette API provides public access, implemented as a web service following a REST/HATEOAS architectural style. Call and presence events are delivered via WebSockets.

Application Requirements

An application using the silhouette API is expected to

•         provide authentication credentials with each request to the API

•         authenticate users connected to the application

•         populate the HTTP User-Agent header with a string identifying the client application

•         limit request rate to avoid exceeding limits

•         handle errors appropriately (interpret response)

Client applications using the silhouette API to manage calls are expected to

•         subscribe for required events

•         associate requests and events and manage the application view of call activity, and so forth

•         track call history, if required

•         not assume events will be received immediately (may be rate limited)

•         initiate and maintain connection to silhouette (for example, use a keep-alive to keep a WebSocket open to receive events)

•         request the current state of a silhouette account when it initially connects (if required). Events are only pushed to the applications as they occur.

Accessing the API

The silhouette API entry point is https://<WebAdmin>/api. Accessing the silhouette API includes

•         API Access

•         Security

•         Load Control

•         SSL Certification

API Access

The Public API is intended for use by client applications deployed in the customer premise. Applications access the Public API through the TOWS, using the existing WebAdmin IP address or FQDN.

See Architecture.

Security

silhouette API security comprises

•         Authentication

•         Authorization

Authentication

An authentication protocol is used for authenticating silhouette API access. All REST requests and the WebSocket connection request must be authenticated individually (no sessions).

Authorization

Authorization is per request and is based on the authority users have to access the API.

Load Control

Load control mechanisms ensure the following on the Public API:

•         WebSockets

•         maxIdleTimeout=3600000 milliseconds (1 hour). Without any data transfer, the WebSocket connection times out after 1 hour.

•         maxConnectionCount=4000. The maximum number of public WebSocket connections.

•         maxConnectionPerClient=1. The maximum number of concurrent processing threads per client. Per client means per user+client IP address.

•         blockAfterFailedLoginCount=3. Client is locked out after 3 failed login attempts.

•         blockFailedLoginWithin=1800000 milliseconds (30 minutes). After 3 failed login attempts within 30 minutes, the client is locked out.

•         blockPeriod=3600000 milliseconds (1 hour). After 3 failed attempts within 30 minutes, the client is locked out for an hour.

•         For REST service calls

•         maxThreads=100. The maximum number of concurrent requests from all clients that the server accepts.

•         maxConnectionPerClient=3. The maximum number of concurrent processing threads per client. Per client means per user+client IP address.

•         busyDelay=3000 milliseconds (3 seconds). When a response is delayed for 3 seconds, the system returns a 503.

•         blockAfterFailedLoginCount=3. Client is locked out after 3 failed login attempts.

•         blockFailedLoginWithin=1800000 milliseconds (30 minutes). After 3 failed login attempts within 30 minutes, the client is locked out.

•         blockPeriod=3600000 milliseconds (1 hour). After 3 failed attempts within 30 minutes, the client is locked out for an hour.

SSL Certification

The silhouette API supports the following versions of Transport Layer Security (TLS):

•         TLS v1.2

The silhouette API supports the TLS SSL ECDHE_* cipher suite, excluding all RC4, MD5, DES, DSS and NULL ciphers.

Using the API

Using the API includes the following topics:

•         Hyperlinking API Fundamentals

•         Using HTTP Verbs

•         API Documentation—The HAL Browser

•         WebSockets

•         WSTool

•         Subscription Sets

•         Using API Features

•         Third Party Call Control

Hyperlinking API Fundamentals

The silhouette API is designed as a hyperlinking RESTful API. Rather than focusing on specific URLs, which may change as the system evolves, a hyperlinking API focuses on exposing relationships between resources and providing the ability to discover available resources. The benefit of this approach is that it results in an explorable API that provides client developers the ability to browse data and interact with the API at design time, which makes it much easier for the client developers to build a mental model of the API and its data structures.

Using HTTP Verbs

The silhouette API supports the following HTTP verbs in compliance with the definitions in the HTTP specification (RFC7231). Note that not all resources of the API support all verbs. See the resource details (online or in this document) for its supported verbs.

•         GET—Retrieves the representation of the resource at the request URL. Some resources accept optional query parameters that let the client refine the content received in the response.

•         HEAD —Performs the same logic on the server as a GET request to the same URL, but does not return any response data. Clients can use this to pre-test whether a GET will be successful.

•         PUT—Creates a new resource or replaces an existing resource at the request URL using the request payload.

•         POST—Tells the service how to modify the contents of the resource at the request URL, particularly when that resource is a container of other resources. Thus, a POST request may create a new subordinate resource if it is a container resource (a POST request to the Call Group list is used to add a new Call Group). If the resource is not a container resource, the POST request may have the effect of

directly modifying the resource at the request URL (a POST request to a Call is used to change the call state).

If a new resource is created as the effect of a POST request, the HTTP response code will be a 201 Created and the HTTP Location header will be populated with the URL of the new resource.

•         DELETE—Deletes the resource at the request URL. A successful response is typically a 200 OK with an empty payload.

The API supports the media type application/json for request payloads, and

application/hal+json in response payloads.

API Documentation—The HAL Browser

The HAL Browser is a web-based user interface that is provided as part of the silhouette API. It lets client developers explore the API’s capabilities. Use it to discover the resources supported in the API, their data structures, and their link relationships.

When accessing The HAL Browser for the first time, you are prompted for credentials. See API Access. Once the credentials have been accepted you can proceed with exploring the API.

Resource Graph

The menu at the top of The HAL Browser has a link to the API Resource Graph. The client developer can expand resource nodes and follow documentation links to explore the Resource Model. The graph documents the full model; however, visibility of resource data in the application is subject to authorization, licensing, and permission controls. See Resource Model.

  The detailed documentation (online and in this document) includes sample Request/

WebSockets

The silhouette API delivers Call and Presence Event Notifications over a WebSocket. You can find out more about the WebSocket protocol at

http://www.websocket.org/aboutwebsocket.html

To establish a WebSocket connection with silhouette, the URL is published in API Root Resource response as the link relation called “v1:createWebSocket”. In the current release, this URL is as follows:

https:<WebAdmin IP>/api/ws

Any valid user credentials can be used.

After the WebSocket connection has been successfully established, a message is sent from the server to the client indicating the UUID of the newly-created WebSocket. This UUID is used in subsequent REST requests to the silhouette API to subscribe to events. Note that there could be a small delay before this message is sent.

Example

===>

wss://{webadmin ip}/api/ws

<===

HTTP/1.1 101 Switching Protocols

Connection: Upgrade Upgrade: WebSocket

<===

{"webSocketId":"aa922613-78ad-4e30-97e1-fac6a6a7e75c"}

The server establishes a timeout interval for the WebSocket connection. If no events are delivered in that period of time, silhouette closes the connection and any subscriptions on the WebSocket are cancelled. Clients can force the connection to stay open by periodically sending a message over the connection. The format of the message may be a short string, such as “hello”. The server will echo this back if the connection is still alive and reset the timeout counter.

The timeout value for connections is set to 1 hour.

WebSockets should be explicitly torn down gracefully by the client before any attempt to establish a new connection.

WSTool

WSTool is a web-based tool that creates a WebSocket connection. It is shipped with the silhouette API, preconfigured to use the createWebsocket URL to establish a connection, and can be used for testing or exploring the API. It requires HTTP basic authentication, the same as the API itself (see Security). Access WSTool at https://

<webadmin IP>/api/wstool/wstool.html.

Subscription Sets

Once it has established a WebSocket, the client can subscribe to events. To receive events, follow these steps:

1.   Establish a WebSocket with the silhouette API.

2.   Receive a WebSocket ID over the newly-established WebSocket.

3.   Use the WebSocket ID to create a Subscription Set for each set of subscriptions.

4.   Create a subscription within the Subscription Set to subscribe for specific events. (Events related to the subscriptions are sent over the WebSocket as they occur.)

Using API Features

The silhouette API includes the following features:

•         Expand Support

•         Filter Support

•         enum lookup

Expand Support

Table of Contents

•         Description

•         Expand Keys

•         Performance

•         Expand Parameter Examples Description

Most resources list or entity (for example: a list of tenants, or a single tenant) support an optional query parameter on the URL that enables the client to request more detail in the query response.

In a query response, many entity representations include information about related resources in the _embedded section of the payload. Similarly, in a list query, each element of the list is included in the _embedded section of the payload. Embedded representations typically include only identifying information about the resource.

However, when a client is interested in more information about some embedded representations than is included by default, it can ask for more detail about those representations to be included in the response by providing the representation name in the value of the expand query parameter.

If the embedded resource contains an array, each element of the array will be expanded. In the case of list resources, such as the tenant list or user list, this allows the client to retrieve detail about every item in the list in a single query.

Expand Keys

The expand parameter value contains one or more expand keys, each expand key can be:

• 

simple keys:

•

item, this special key only used in a list resource context, it means item of the list.

•

all, this special key means expand all possible embed resources of an entity resource.

•

<valid embed name of entity>, this means expand the specified embed resource of an entity resource.

•

-<valid embed name of entity>, minus sign can be used to specify not expand the specified embed resource, which is useful when together with the

all key to exclude the specified embed resource.

• 

multi-level keys: (combination of simple keys)

•

<valid embed name of entity>.item, this means expand the embedded resource, not include embedded of the embedded resource.

•

<valid embed name of entity>.all, this means expand the embedded resource, include all embedded of the embedded resource.

•

<valid embed name of entity>.<valid embed name>, this means expand the specified embed resource of specified embed resource of the

entity.

•

-<valid embed name of entity>.<valid embed name>, minus sign

can be used to specify not expand the specified embed resource of specified embed resource of the entity, which is useful when together with the <valid embed name of entity>.all key.

•

Recursive expansion can be specified by identifying the desired tokens using

dot-notation to specify the path to the embedded resource within the embedded resource, there is no limitation of how many level can be expanded.

When more than one expand key provided, they must be separated by coma.

Any unrecognized key include embed name of embed resource not accessible for user will be ignored.

When expand any embed resource, the owner of the embed resource will be expanded as well (the item will be implicitly included).

When expand any entity(include embedded resource), it only expand one level, which means it will include all attributes of the entity(visible by user role), and un-expanded view of all embedded resource of the entity, if need expand next level, next level expand key have to be provided in the parameter value.

When using embed name as expand key, must exactly (case-sensitively) match the name of the embedded resource to include.

Performance

When expand parameter included, the more content included and more level content included, the more time it will be cost to build the response and the much bigger size of the response will be.

It is up to the client to judge the query performance based on their requirements. Expand Parameter Examples

Here are some examples of getting a list of user with expand parameters:

GET /api/v1/tenants/414/users?expand=item GET /api/v1/tenants/414/users?expand=all

GET /api/v1/tenants/414/users?expand=all,-keyProfile

GET /api/v1/tenants/414/users?expand=featureSettings,adminSettings GET /api/v1/tenants/414/users/100?expand=all

GET /api/v1/tenants/414/users/100?expand=callPermissionProfile

Filter Support

Table of Contents

•         Description

•         Filter condition

•         value condition

•         non-value condition

•         Performance

•         Filter Parameter Examples Description

Filtering result of GET request on all List resources is supported by optional filter

query parameter.

When multiple filter parameters provided, the logical relation between these filters are AND which means the result will only include items match all filters.

Filter condition

Each filter parameter value contains one or more filter conditions.

When more than one condition provided, they must be separated by coma.

When more than one filter conditions in the filter parameter value, the logical relation between filter conditions are OR relation which mean any item match any one of the filter conditions will be included in the result.

Each filter condition must match valid format, if NOT, will get 400 bad request error. There are 2 type of filter conditions: value condition and no-value condition. value condition

Value condition means compare the current value of an attribute of resource or embed resource with a provided value.

Each value condition format is:

<operator>(<key>,<value>)

value condition operators

value condition key

• 

Key must be either a <valid property name> of the item resource of the list or a

<valid property name> of a valid embed resource of the item resource.

• 

Only property or embedded which is visible to the user can be used as key

• 

Multi level embed resources and properties is valid for filter condition key value,

such as:

•

<valid embed name>.<valid embed name>…<valid embed name>.<valid property name>

•

Note: the above condition implicitly indicate that every higher level embed must be exist

value

• 

• 

value must be provided

value must match expected value type

• 

string value should not be quoted and must be URI encoded if contains URI special

characters

value condition examples eq(active,false) ci(firstName,Steven)

sw(keyProfile.name,Sales)

non-value condition

format: <operator>(<key>)

non-value condition operators

non-value condition key

• 

key must be: <valid property name or valid embed name> of the item resource of the list or <valid property name or valid embed name> of a valid embed resource of the item resource.

• 

only property or embedded which is visible to the user can be used as key

• 

Multi level embed resources and properties is valid for filter condition key value,

such as:

•

<valid embed name>.<valid embed name>…<valid embed name>

•

<valid embed name>.<valid embed name>…<valid embed name>.<valid

property name>

•

Note: the above condition implicitly indicate that every higher level embed

must be exist

non-value condition examples

est(keyProfile) emp(feature.callForwardNoAnswer.callTarget) Performance

When filter parameter included, it will cause server processing time slightly increase, while it may reduce the network transfer time if the result list getting smaller.

When multiple filter parameter provided, the order in the URI will affect performance, the better performance can be achieved by put the more restricted filter more closer to beginning of the query parameter. For example, the filter of filter user by name equals Steven should be put before user do not have a key profile.

When use more than one condition in a filter, better performance can be achieved by put the less restricted condition before more restricted condition. For example, you should be put user do not have a key profile before name equals Steven.

Filter Parameter Examples

Here is an example query URI for get a list of user with filter to ask for users which extension start with 2 or 3 and no key profile:

GET /api/v1/tenants/414/users? filter=sw(extension,2),sw(extension,3)&filter=nes(keyProfile)

enum lookup

As a client development aid, the silhouette API provides an enum lookup service for enumerated type values used in the API. This service provides a list of valid values that can be used for the indicated property. A hyperlink is provided to each enum value from the resource that uses it.

For example, the POST Call request has a required field called callRequest:

POST /calls/3501-1441389611741-3%3A155@12345

{"callRequest":"hangupCall", "myPartyId":"155@12345", "deviceId":"4564",

}

The GET Call response includes a hyperlink to the enum lookup resource for the

callRequest field:

GET /calls/3501-1441389611741-3%3A155%4012345 HTTP/1.1

Response:

{

"_links" : {

"curies" : {

"href" : "/api/v1/rels/{rel}", "name" : "v1options", "templated" : true

},

"self" : {

"href" : "/calls/3501-1441389611741-3:155@12345"

},

"v1options:callRequest" : {

"href" : "/api/v1/enums/callrequest"

}

},

"answerTime" : "2016-03-18T13:05:14.216-04:00", "callId" : "3501-1441389611741-3:155@12345",

"callParties" : [ { "PartyId" : "155@12345",

"PartyName" : "User, Jane"

}, {

"PartyId" : "203@12345",

"PartyName" : "User, Joe"

} ],

"callState" : "connected", "digitsDialed" : "203", "from" : "203@12345",

"redirected" : false,

"startTime" : "2016-03-18T13:04:44.260-04:00",

"talkDuration" : "PT45S", "to" : "155@12345",

"transferred" : false

}

You can issue a GET request to the href value indicated by the v1options:callRequest link to see the list of valid values that can be used for the callRequest field:

GET /api/v1/enums/callrequest

The response includes a list of valid values:

{

"_links": {

"self": {

"href": "/api/v1/enums/callrequest"

}

},

"values": [

{

"name": "answerCall", "defaultLabel": "answerCall"

},

{

"name": "hangupCall", "defaultLabel": "hangupCall"

}

]

}

The string value in the name property can be used as the value of the callRequest

property in subsequent POST requests to modify the call state.

By programmatically parsing it at runtime, client can ensure they are using the correct string value.

Third Party Call Control

The purpose of a Third Party Call Control API is to enable applications to monitor calls, and to invoke requests to make calls, and modify existing calls.

Details on how to initiate a call, retrieve a parked call, and query a user’s active calls are documented in the ActiveCalls Resource section of Call Management Resources. Commands to answer, hang up, or invoke call features are documented in the Call Resource section of Call Management Resources.

It is possible to monitor call activity using Events received over a WebSocket. In order to receive Call, Presence, or ParkLocation events, a Subscription Set must be created, and the client must register for specific events. The details on how to register for events are documented in the Event Management Resources section.

Detail on the Event content is contained in the Events section.

It is also possible to get the current status information of a user or park location as described in the Presence Status Resource and ParkLocation Status Resource. This is normally used by an application that has registered for events to get an initial status.

Third Party Call Control Commands

The silhouette API includes the following Third Party Call Control (3PCC) commands. All commands are supported for MiNET and VVX devices. The following table shows which commands are supported for BSTs (Basic SIP Terminals).

For more information, see API Resources and Subscription Sets.

makeCall

Description

Places a call. Allows the user to place the call from an external number as part of the Bring Your Own Number (BYON) feature. The feature still places a call from the user’s default device when no device is specified.

Details

https://{ip}/api/v1/calls

{"request":"makeCall" "from":"102@tenantId", "to":"912125551212",

"deviceIdType":"external", "deviceId": "{external number}"}

For a basic SIP terminal (BST) to support makeCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

getCalls

Description

Gets a list of active calls for the authorized user.

Details

https://{ip}/api/v1/calls/{callObserverId}

For a basic SIP terminal (BST) to support getCalls, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

getCall

Description

Gets the details of a particular call based on the callObserverId.

Details

https://{ip}/api/v1/calls/{callObserverId}

For a basic SIP terminal (BST) to support getCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

parkCall

Description

Parks a specific call based on the callId.

To Park a call at system-generated (generic) location, remove featureData from the request body.

Details

https://{ip}/api/v1/calls/{callId}

{"callRequest":"parkCall", "myPartyId":"105@tenantId", “featureData”:”4”}

For a basic SIP terminal (BST) to support parkCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

answerCall

Description Answers a call.

Details

https://{ip}/api/v1/calls/{callObserverId}

{"callRequest":"answerCall", ”myPartyId”:"ext@tenantId"}

hangupCall

Description Hangs up a call.

Details

https://{ip}/api/v1/calls/{callObserverId}

{"callRequest":"hangupCall"}

For a basic SIP terminal (BST) to support hangupCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

deflectCall

Description

Deflects a ringing call to coverage. Details

https://{ip}/api/v1/calls/{callId}

{"callRequest":"deflectCall", "myPartyId":"105@tenantId" }

For a basic SIP terminal (BST) to support deflectCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

holdCall

Description

Holds a specific call based on the callId.

Details

https://{ip}/api/v1/calls/{callId}

{"callRequest":"holdCall", "myPartyId":105@tenantId }

resumeCall

Description

Resumes a specific call based on the callId from a hold state.

Details

https://{ip}/api/v1/calls/{callId}

{"callRequest":"resumeHeldCall", "myPartyId":"105@tenantId" }

transferCall

Description

Transfers active and held calls. Details

https://{ip}/api/v1/calls/{callId2}

{"callRequest":"transfer", "myPartyId":"105@tenantId", "otherCallId":"{callId1}" }

For a basic SIP terminal (BST) to support transferCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

retrieveCall

Description

Retrieves a parked call at a park location referenced by featureData. Details

POST https://{ip}/api/v1/calls

{"request":"retrieveParkedCall" "from":"102@tenantId", "featureData”:”4" "deviceIdType":"device", "deviceId": "23"}

For a basic SIP terminal (BST) to support retrieveCall, the SIP phone must

•         be able to handle a minimum of two calls concurrently

•         have an available line appearance

•         accept reINVITEs

•         be able to send reINVITEs

Events

Applications use the Subscription Set Resource to subscribe to accounts. See Event Management Resources. Applications can subscribe to Call Events, Presence Events and ParkLocation Events. Events are streamed through a WebSocket and include

a callId, which is necessary for tracking calls for each subscriber involved. The smdrCallId in Third Party Call Control (3PCC) events correlates with the callid in the SMDR records and optionally in call segments if Segmented SMDR is enabled.

Call Events

Call events provide the necessary information for tracking calls. Call events reference a callId, which can be used to associate events common to a single call on the account. Call events also reference the account. Call events report basic call events such as dial, ring, answer, offer, and end—although not all information is included in each event. Calls start with either an offer (incoming) or dial (outgoing) event and end with an “end” event. When a client starts up, if it tracks calls, it can get current calls to find out about existing calls. See ActiveCalls Resource and Call Management Resources. After that the events should provide all needed information.

Feature events including hold, resume, forward, and transfer are reported as call events. Call events are pushed to each subscribed application as they occur. Call events report the same basic information on accounts as the legacy call events, but are not identical. Call events reference the phone used by the associated user or location when relevant (events such as Answer).

General Format

===>

https://{webadminIP}/api/v1/calls

dial

Description

Account has dialed a call. Details

{

“subscriptionSetId”:”12345”, “event”:”dial”,

“callId”:1, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “from”:”100@Windstream”, “to”:”101@Windstream”,

“sipCallId”:”[email protected]”, “dialingDeviceId”:1

}

ringback

Description

Dialed call is ringing.

Details

{

“subscriptionSetId”:”12345”, “event”:”ringback”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”

}

offer

Description

Call has been offered to account. Details

{

“subscriptionSetId”:”12345”, “event”:”offer”,

“callId”:1, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “from”:”101@Windstream”, “to”:”100@Windstream”, “via”:”102@Windstream”,

“sipCallId”:”[email protected]”, “dialedDigits”:“100”,

“callingName”:”Homer Simpson”

}

ringing

Description

Call offered to account is ringing on a particular phone. Details

{

“subscriptionSetId”:”12345”, “event”:”ringing”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “ringingDeviceId”:1

}

answer

Description

Ringing call offered to account has been answered on a particular phone, or dialed call has been answered.

Details

{

“subscriptionSetId”:”12345”, “event”:”answer”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “answeringParty”:”101@Windstream”, “answeringDeviceId”:2

}

forward

Description

Call has been forwarded. Details

{

“subscriptionSetId”:”12345”, “event”:”forward”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

"version”:”v1”, “forwardingParty”:”101@Windstream”, “forwardTarget”:”102@Windstream”

}

hold

Description

Call has been put on hold. Details

{

“subscriptionSetId”:”12345”, “event”:”hold”,

“callId”:1, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “holdingParty”:”100@Windstream”, “heldParty”:”101@Windstream”

}

held

Description

Issued for the held party when a call is put on hold. Details

{

“subscriptionSetId”:”12345”, “event”:”hold”,

“callId”:1, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “holdingParty”:”100@Windstream”, “heldParty”:”101@Windstream”

}

resume

Description

Held call has been resumed. Details

{

“subscriptionSetId”:”12345”, “event”:”resume”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “resumingParty”:”100@Windstream”, “heldParty”:”101@Windstream”

}

resumed

Description

Issued to the held party when a call is taken off hold. Details

{

“subscriptionSetId”:”12345”, “event”:”resume”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “resumingParty”:”100@Windstream”, “heldParty”:”101@Windstream”

}

transfer

Description

Call has been transferred. Details

{

“subscriptionSetId”:”12345”, “event”:”transfer”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “transferringParty”:”100@Windstream”, “transferee”:”101@Windstream”, “transferTarget”:”102@Windstream”

}

callError

Description

Call cannot be completed and has been forwarded to treatment. Details

{

“subscriptionSetId”:”12345”, “event”:”callError”, “callId”:1,

“observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “error”:”Subscriber unavailable”

}

end

Description

Account is no longer involved in a call . Details

{

“subscriptionSetId”:”12345”, “event”:”end”,

“callId”:1, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52-04”,

“version”:”v1”, “from”:”100@Windstream”, “to”:”101@Windstream”, “endingParty”:”100@Windstream”, “endReason”:”normal”, “callDuration”:”PT3M25S”

}

park

Description

Issued for the parking party when an account parks a call. Details

{

“callId”:1, "parkingPartyNumber"."100", "parkLocationId"."1", "observedParty"."120", "parkedPartyNumber"."101", “subscriptionSetId”:”12345”, “event”:”park”, "parkingPartyName"."Jack Slack", “version”:”v1”, “parkedPartyName”:”Joe Schmo” “timestamp”:”2015-05-11T14:06:52-04”,

}

parked

Description

Issued for the parked party when a call is parked. Details

{

“callId”:1, "parkingPartyNumber"."100", "parkLocationId"."1", "observedParty"."120", "parkedPartyNumber"."101", “subscriptionSetId”:”12345”, “event”:”park”, "parkingPartyName"."Jack Slack", “version”:”v1”, “parkedPartyName”:”Joe Schmo” “timestamp”:”2015-05-11T14:06:52-04”,

}

retrieve

Description

Issued for the retrieving party when an account retrieves a call from the parked state. Details

{

“callId”:1, "retrievingPartyName"."Joe Schmo", "parkLocationID"."3", "observedPartyID"."100@5556661111", "parkedPartyNumber"."100", “subscriptionSetId”:”12345”, “event”:”retrieve”,

“version”:”v1”, “retrievingPartyID”:”101”, “parkedPartyName”:”Jack Slack” “timestamp”:”2015-05-11T14:06:52-04”,

}

retrieved

Description

Issued for the parked party when a call is retrieved from park. Details

{

“callId”:1, "retrievingPartyName"."Joe Schmo", "parkLocationID"."3", "observedPartyID"."100@5556661111", "parkedPartyNumber"."100", “subscriptionSetId”:”12345”, “event”:”retrieved”, “version”:”v1”, “retrievingPartyID”:”101”, “parkedPartyName”:”Jack Slack”

“timestamp”:”2015-05-11T14:06:52-04”,

}

Presence Events

Presence Events must be reported from the perspective of a single user or location extension. Currently, presence events are relevant only for users and locations. The application must explicitly subscribe for presence events for specific accounts. All presence events include a reference to the account, rather than particular calls. Clients that track presence status will want to get the current presence status of users at the same time that they register for presence events. See PresenceStatusByExtension Resource.

Presence events report basic account status such as idle, busy, available for calls, unavailable for calls, joined group, left group, available for ACD, unavailable for ACD. Presence events are pushed as they occur to each subscribed application.

The sipCallId header may or may not be present in the dial, offer, ringback, ringing, and answer events. To be included at any point in a call flow, the call must include at least one SIP endpoint (device, gateway, and so forth.). The particular events in a call event stream that contain a sipCallId header depends on the call scenario.

The via header may or may not be included in the offer event, depending on the call scenario.

idle

Account is not involved in any calls. Details

{

“subscriptionSetId”:”12345”, “event”:”idle”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

busy

Account is involved in one or more calls. Details

{

“subscriptionSetId”:”12345”, “event”:”busy”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

available

Account is available to receive calls (that is, logged in to at least one, connected device). Details

{

“subscriptionSetId”:”12345”, “event”:”available”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

unavailable

Account is not available to receive calls (i.e., account is not logged into any connected devices.

Details

{

“subscriptionSetId”:”12345”, “event”:”unavailable”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

joinedGroup

Account has joined a group. Details

{

“subscriptionSetId”:”12345”, “event”:”joinedGroup”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”, “groupJoined”:”600@Windstream”

}

leftGroup

Account has left a group. Details

{

“subscriptionSetId”:”12345”, “event”:”leftGroup”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”, “groupLeft”:”600@Windstream”

}

signedInAcd

Account is available to participate in ACD applications. Details

{

“subscriptionSetId”:”12345”, “event”:”signedInAcd”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

signedOutAcd

Account is unavailable to participate in ACD applications. Details

{

“subscriptionSetId”:”12345”, “event”:”signedOutAcd”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

dndOff

Account has turned DND off. Details

{

“subscriptionSetId”:”12345”, “event”:”dndOff”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

dndOn

Account has turned DND on. Details

{

“subscriptionSetId”:”12345”, “event”:”dndOn”, “observedParty”:”100@Windstream”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

ParkLocation Events

ParkLocation Events must be reported from the perspective of a single Park Location. The application must explicitly subscribe for ParkLocation events for specific Park Location or all Park Locations in a tenant. All ParkLocation events include a reference to the Park Location. Clients that track ParkLocation status will want to get the

current ParkLocation status of a ParkLocation at the same time that they register for ParkLocation events. See ParkLocationStatus Resource.

ParkLocation events report basic Park Location status such as idle, busy. ParkLocation events are pushed as they occur to each subscribed application.

idle

ParkLocation is not involved in any calls. Details

{

“subscriptionSetId”:”12345”, “event”:”idle”, “observedParty”:”PL1@315100001”, “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

busy

ParkLocation is involved in one or more calls. Details

{

“subscriptionSetId”:”12345”, “event”:”busy”, “observedParty”:”PL1@315100001”, "parkedParty":"6132805555", "parkedPartyName":"Steve L" “timestamp”:”2015-05-11T14:06:52+04”,

“version”:”v1”

}

API Resources

This section includes

•         Resource Model

•         Navigation Resources

•         Event Management Resources

•         Call Management Resources

•         Presence Status Resources

•         ParkLocation Status Resources

•         Provisioning Resources

  The detailed documentation in this chapter includes references to information that

Resource Model

You can view the complete interactive graph online at https://<webadminIP>/api/ browser/graph.html or using the “Resource Graph” link in the HAL browser. You can view a whole list of all resource models online at https://< webadminIP>/api/ browser/list.html or using the “Resource List” link in the HAL browser.

Navigation Resources

Navigation resources include:

•         API Root Resource—the API entry point; this resource varies depending on the authorization of the requesting user.

•         V1 Resource—the entry point to the V1 of the API; this resource varies depending on the authorization of the requesting user.

•         URI Template Dictionary—provides a list of URL templates of major resources supported by the API.

•         Enums List Resource—provides a list of all enum types used by the application.

•         Enum Resource—describes the general response format to a query for enum details.

API Root Resource

Table of Contents

•         Description

•         Supported Operations

•         Permitted Authorities (as defined in API Guide)

•         Resource Details

•         Properties

•         Link Relations

•         Sample GET Response Description

This resource is the entry point of the silhouette API.

This resource returns a list of potential resources an application client may wish to navigate to as a logical next step in using the silhouette API.

If the end user making the request is restricted to viewing data within a tenant, then basic information about that tenant will also be returned in this response.

Supported Operations

GET

View API Root resource HEAD

Get just the header response

Permitted Authorities (as defined in API Guide)

Resource Details

Properties

Link Relations

Sample GET Response

HTTP/1.1 200 OK

Content-Type: application/hal+json Content-Length: 353

{

"_links" : {

"curies" : {

"href" : "/api/releases/{rel}", "name" : "api",

"templated" : true

},

"self" : {

"href" : "/api"

},

"api:createWebsocket" : { "href" : "/api/ws"

},

"api:v1" : {

"href" : "/api/v1"

}

},

"tenantId" : 156,

"tenantName" : "Dave's Moose Hunting Supply"

}

V1 Resource

Table of Contents

•         Description

•         Supported Operations

•         Permitted Authorities (as defined in API Guide)

•         Resource Details

•         Link Relations

•         Sample GET Response Description

This relation returns a list of resources that an application client may wish to allow the end user to view and manage.

The content of this resource varies depending on the role and identity of the end user initiating the request.

·         TelcoAdmin users with Tenant Management permission will be provided with a link to explore tenant resources in the system

·         TelcoAdmin users with Tenant Scope and Call Control Management permission will

be provided with links to manage their event subscription sets and the presence status for users within their tenant

·         TenantAdmin users will be provided with links to explore the details of their tenant’s

data, their personal data, as well as links to manage their event subscription sets and view their own presence status

·         Non-admin users (Users and Locations) will be provided with links to explore details

of their own system usage.

Supported Operations

GET

View V1 resources HEAD

Get just the header response

Permitted Authorities (as defined in API Guide)

Resource Details

Link Relations

Sample GET Response

HTTP/1.1 200 OK

Content-Type: application/hal+json Content-Length: 5603

{

"_links" : {

"curies" : {

"href" : "/api/v1/rels/{rel}", "name" : "v1",

"templated" : true

},

"self" : {

"href" : "/api/v1"

},

"v1:aaLanguages" : {

"href" : "/api/v1/aalanguages{?filter}", "templated" : true

},

"v1:activeCalls" : { "href" : "/api/v1/calls"

},

"v1:appServers" : {

"href" : "/api/v1/appservers{?expand,filter}", "templated" : true

},

"v1:brandDetails" : {

"href" : "/api/v1/branddetails{?filter}", "templated" : true

},

"v1:callpServers" : {

"href" : "/api/v1/callpservers{?expand}", "templated" : true

},

"v1:carriers" : {

"href" : "/api/v1/carriers{?expand,filter}", "templated" : true

},

"v1:codecSets" : {

"href" : "/api/v1/codecsets{?expand,filter}", "templated" : true

},

"v1:conferenceServers" : {

"href" : "/api/v1/conferenceservers{?expand,filter}", "templated" : true

},

"v1:crPlatforms" : {

"href" : "/api/v1/crplatforms{?expand,filter}", "templated" : true

},

"v1:customAnnouncementFiles" : {

"href" : "/api/v1/customannouncementfiles/{langCode}{?filter}", "templated" : true

},

"v1:customDhcpOptions" : {

"href" : "/api/v1/customdhcpoptions{?filter}", "templated" : true

},

"v1:defaultAnnouncementFiles" : {

"href" : "/api/v1/defaultannouncementfiles/{langCode}{?filter}", "templated" : true

},

"v1:defaultSystemAnnouncement" : {

"href" : "/api/v1/defaultsystemannouncement{?expand}", "templated" : true

},

"v1:defaultSystemCodecSet" : {

"href" : "/api/v1/defaultcodecset{?expand}", "templated" : true

},

"v1:deviceStates" : {

"href" : "/api/v1/devicestates"

},

"v1:dialPlans" : {

"href" : "/api/v1/dialplans{?expand,filter}", "templated" : true

},

"v1:enterprises" : {

"href" : "/api/v1/enterprises{?expand,filter}", "templated" : true

},

"v1:eventSubscriptionSets" : {

"href" : "/api/v1/subscriptions/ws/{webSocketId}/subscriptionsets", "templated" : true

},

"v1:extensions" : {

"href" : "/api/v1/tenants/156/extensions{?expand,filter,extensionType,agent}", "templated" : true

},

"v1:externalContacts" : {

"href" : "/api/v1/tenants/156/externalcontacts{?expand,filter}", "templated" : true

},

"v1:gateways" : {

"href" : "/api/v1/gateways{?expand,filter}", "templated" : true

},

"v1:languages" : {

"href" : "/api/v1/languages{?filter}", "templated" : true

},

"v1:licensing" : {

"href" : "/api/v1/licensing"

},

"v1:macAddresses" : {

"href" : "/api/v1/macaddresses?macAddress={macAddress}", "templated" : true

},

"v1:mediaServers" : {

"href" : "/api/v1/mediaservers{?expand,filter}", "templated" : true

},

"v1:parkLocationStatus" : {

"href" : "/api/v1/presencestatus/parklocationstatus/{accountId}", "templated" : true

},

"v1:phoneAccessEntries" : {

"href" : "/api/v1/phoneaccessentries{?expand,filter}", "templated" : true

},

"v1:pinNotificationSettings" : {

"href" : "/api/v1/pinnotificationsettings"

},

"v1:presenceStatusByExtension" : {

"href" : "/api/v1/presencestatus/tenants/156/extensions/4332"

},

"v1:presenceStatusTenantAccounts" : {

"href" : "/api/v1/presencestatus/tenants/156/extensions"

},

"v1:presenceStatusTenantParkLocations" : {

"href" : "/api/v1/presencestatus/tenants/156/parklocations"

},

"v1:priGroups" : {

"href" : "/api/v1/prigroups{?expand,filter}", "templated" : true

},

"v1:routes" : {

"href" : "/api/v1/routes{?expand,filter}", "templated" : true

},

"v1:rtpProxyServers" : {

"href" : "/api/v1/rtpproxyservers{?expand,filter}", "templated" : true

},

"v1:runningTasks" : {

"href" : "/api/v1/runningtasks{?expand,filter}", "templated" : true

},

"v1:sendMessageSites" : {

"href" : "/api/v1/sendmessage/tenants/156/alertsites"

},

"v1:sendMessageUsers" : {

"href" : "/api/v1/sendmessage/tenants/156/alertusers"

},

"v1:serviceProviders" : {

"href" : "/api/v1/serviceproviders{?expand,filter}", "templated" : true

},

"v1:standardDhcpOptions" : {

"href" : "/api/v1/standarddhcpoptions{?expand,filter}", "templated" : true

},

"v1:systemAnnouncements" : {

"href" : "/api/v1/systemannouncements{?expand,filter}", "templated" : true

},

"v1:systemProperties" : {

"href" : "/api/v1/systemproperties"

},

"v1:tenant" : {

"href" : "/api/v1/tenants/156"

},

"v1:tenantPhoneModels" : {

"href" : "/api/v1/tenants/156/phonemodels{?expand,filter}", "templated" : true

},

"v1:tenants" : {

"href" : "/api/v1/tenants{?expand,filter}", "templated" : true

},

"v1:uriDictionary" : {

"href" : "/api/v1/uridictionary"

},

"v1:user" : {

"href" : "/api/v1/tenants/156/users/4332"

},

"v1:userPhones" : {

"href" : "/api/v1/tenants/156/users/4332/phones{?expand,filter}", "templated" : true

},

"v1:vmLanguages" : {

"href" : "/api/v1/vmlanguages{?filter}", "templated" : true

},

"v1:voicemailServers" : {

"href" : "/api/v1/voicemailservers"

},

"v1:zones" : {

"href" : "/api/v1/zones{?expand,filter}", "templated" : true

}

}

}

URI Template Dictionary

Table of Contents

•         Description

•         Supported Operations

•         Permitted Authorities (as defined in API Guide)

•         Resource Details

•         Properties

•         Link Relations

•         Expandable Relations

•         Sample GET Response Description

This resource is the URI Template Dictionary of the silhouette API. It returns a list of URI Templates of frequently used links which can be used to access a single Entity Resource.

Each list of resources in the service publishes an itemTemplate link relation that provides a templated URI that the client can use in conjunction with a known identifier value to resolve the URI to a specific instance URL. This resource gathers those templates into a single place so that a client that is identifier-aware can cache the templates and resolve them as required, which may help to reduce the number of required round-trip queries.

The URI Template Dictionary only provides URI Templates links visible to Telco and TenantAdmin users.

Supported Operations

GET

View URI Template Dictionary resources HEAD

Get just the header response

Permitted Authorities (as defined in API Guide)

Resource Details

Properties

This resource has no configurable properties.

Link Relations