UCaaS Calls API Specification

This document defines a RESTful, JSON-based, HTTPS UCaaS API for a telecommunications cloud calling service. The API is designed to be a single, normalized Cloud API layer over one or more provider systems used to provide cloud calling services.

The specification is designed for a generic cloud calling service. Zilkr’s largest production deployment of this API is an enablement for a Cisco BroadSoft service provider, and an integration of the Zilkr Calls API platform over a Cisco BroadSoft platform takes less than 1 day to go live.

Key concepts

Common to any communications system, the following key concepts exist in the API:

A Call is an active call against a subscriber/user in a service provider’s network.
A Subscriber is a user in the service provider’s cloud calling system.
An App is the 3rd party entity that gets access to, integrates with and uses the API.

This API executes either in the Zilkr AWS cloud or a private datacenter, with the integration to a provider’s cloud calling system part of this API cloud. Zilkr is typically given administrator API credentials and uses this to connect to the provider’s network.

Glossary

API Resources:

Calls are active calls in the cloud calling system, e.g. a Cisco BroadSoft platform call.
Apps are 3rd party systems that integrate with and use this Zilkr UCaaS Calls API.
Subscribers are the cloud calling system’s subscriber/user that may see call activity.

API Actions:

Creation of a call, defined by a POST HTTP method.
Retrieval of a list of active calls, defined by a GET HTTP method.
Management of existing calls, defined by PUT and DELETE HTTP methods.

Specification

Calls

Place and manage subscriber calls.

In this API, an app_id is a unique application id given to a 3rd party application on registration with the system. A call_id is a unique identifier for an in-process call resource that is typically sent by the API to an application in an event notification via the Calls Webhook.

Place a new call

POST /apps/{app_id}/calls

JSON input payload:

{
    subscriber_id: 'someSubscriberId@example-telco.com',
    subscriber_number: '+15128675309',
    remote_number: '+15129104114',
    subscriber_name: 'Tommy Tutone',
    remote_name: 'Zilkr LLC'
}

where subscriber_id, subscriber_number and remote_number are required.

Returns 201 Created

JSON output payload:

{
    subscriber_id: 'someSubscriberId@example-telco.com',
    subscriber_number: '+15128675309',
    remote_number: '+15129104114',
    subscriber_name: 'Tommy Tutone',
    remote_name: 'Zilkr LLC',
    call_id: 'callhalf-13467354071:0',
    direction: 'outgoing'
}

Get a list of active calls

GET /apps/{app_id}/calls

JSON input payload: None

Returns 200 OK

JSON output payload:

[{
    subscriber_id: 'someSubscriberId@example-telco.com',
    subscriber_number: '+15128675309',
    remote_number: '+15129104114',
    subscriber_name: 'Tommy Tutone',
    remote_name: 'Zilkr LLC',
    call_id: 'callhalf-13467354071:0',
    direction: 'outgoing'
}]

Get a list of active calls filtered by subscriber

GET /apps/{app_id}/subscribers/{subscriber_id}/calls

JSON input payload: None

Returns 200 OK

JSON output payload:

[{
    subscriber_id: 'someSubscriberId@example-telco.com',
    subscriber_number: '+15128675309',
    remote_number: '+15129104114',
    subscriber_name: 'Tommy Tutone',
    remote_name: 'Zilkr LLC',
    call_id: 'callhalf-13467354071:0',
    direction: 'outgoing'
}]

Answer a ringing call

PUT /apps/{app_id}/calls/{call_id}/answer

JSON input payload: None

Returns 204 No Content
Put an active call on hold

PUT /apps/{app_id}/calls/{call_id}/hold

JSON input payload: None

Returns 204 No Content
Make a held call active again

PUT /apps/{app_id}/calls/{call_id}/resume

JSON input payload: None

Returns 204 No Content
End a call

DELETE /apps/{app_id}/calls/{call_id}

JSON input payload: None

Returns 204 No Content

Calls Webhook

Get notified on call activity

Notification Webhook

POST {your webhook} where {your webhook} is an HTTPS URL on which the Zilkr API should send call events to

JSON payload in this POST:

{
    app_id: 'e1c1eef6-8c12-4031-8cc9-ae667c839476'
    subscriber_id: 'someSubscriberId@example-telco.com',
    subscriber_number: '+15128675309',
    subscriber_name: 'Tommy Tutone',
    subscriber_account_id: 'someCustomerIdOrSiteOrName',
    remote_number: '+15129104114',
    remote_name: 'Zilkr LLC',
    call_id: 'callhalf-13467354071:0',
    sequence_number: '2',
    direction: 'incoming',
    state: 'ringing',
    timestamp: 1533331051226
}

Expects a 200 OK response when the provided webhook is POST‘ed to

Subscriber Webhook

Get notified on new subscribers

The API notifies an application when a service provider subscriber has been provisioned to use the application

Notification Webhook

POST {your webhook} where {your webhook} is an HTTPS URL on which the Zilkr API should send subscriber events to

JSON payload in this POST:

{
    app_id: 'e1c1eef6-8c12-4031-8cc9-ae667c839476'
    subscriber_id: 'someSubscriberId@example-telco.com',
    subscriber_number: '+15128675309',
    subscriber_name: 'Tommy Tutone',
    subscriber_account_id: 'someCustomerIdOrSiteOrName',
    network_id: '7fa63706-39c8-44c8-bf1b-f0749dda9110'
}

Expects a 200 OK response when the provided webhook is POST‘ed to

Next steps

For UCaaS providers using a Cisco BroadSoft platform, this Zilkr UCaaS Calls API can be your calls API in less than 1 day.

Get started by sending us a message.

Send a message

Key concepts

Glossary

Specification

`Calls`

`Calls Webhook`

`Subscriber Webhook`

Next steps