Skip to main content

Configuration Manager

For admins with access to Configuration Manager

For admins with access to Configuration Manager

Zylinc API User Guide

Updated

Description

The Zylinc API is a public web API that enables external customers and partners to integrate with Zylinc Cloud. This document describes how to use the Zylinc API.

Content

Change log

API Version Release Date Changes
V1 June 2022 First release with basic functionality.
V1 November 2022 Added endpoints for call control.
V1 December 2022 Added endpoints for getting conversations.
V1 January 2023 Added SignalR hub and endpoints for getting users, agent sessions, presence, conversations and setting presence.
V1 May 2024 Added Navigator Time Registration call export
V1 December 2024 Added feed URL to API contracts NuGet package
V1 January 2025 Added more info about authentication
V1 November 2025 Added Transcription API

Public URL

To find the public URL of the API you can open the Web Agent in your Zylinc Cloud installation. In the web browser's address bar you can see the URL of the Web Agent.

In the example above the base path of your Zylinc Cloud installation is highlighted in yellow. The base URL of the API is

https://[TenantBasePath]/api/open/v1

In the example above the API base URL is https://novus.zylinc.cloud/t1n/api/open/v1 

The API version is part of the path. The current version is "v1". This version will only change if breaking changes are made to the existing endpoints. Adding more endpoints does not change the API version.

Configuration

API clients are configured in the Configuration Manager web application in Zylinc Cloud under the section Zylinc Open API. You can define as many API clients as you need by clicking on the API clients link. Each API client can be enabled or disabled.

Authentication

The API is protected from unauthorized access by requiring a JSON Web Token (JWT) inserted as a Bearer token in every HTTP request header. The token is acquired from the authentication service running in the Zylinc Cloud installation.

The API uses two types of authentication scopes

Application scope - This scope is used for endpoints where a user (agent) identity is not needed. For example for ordering a callback. An access token for this scope can be acquired in a non-interactive mode using a Client ID and a Client Secret. This scope uses a Client Credentials OAuth flow.

User scope - This scope is used for endpoints where a user (agent) identity is required. For example for call handling. An access token for this scope is acquired using an interactive login flow where the token is passed in a callback given by a Redirect URI. This scope uses an Authorization Code OAuth flow with PKCE enabled. This flow requires a Redirect URI which will complete the OpenID Connect protocol sign-in handshake with the authentication service.

The required authentication scope for each endpoint is documented in the Swagger API documentation.

The Client ID, Client secret and Redirect URI for an Open API client is configured in the Configuration Manager.

Redirect URI

The Redirect URI you configure in Configuration Manager will have this format if you use an ASP.NET client

https://[some.domain.com]/signin-oidc

where some.domain.com is the public hostname of the app that uses the Open API. The redirect URI must be public accessible and use SSL.

Example Code

Client Credentials Authentication

How to use Application scope authentication.

You can get an access token using the Client Credentials flow with an HTTP POST request to the authentication service as shown below:

curl -X POST https://novus.zylinc.cloud/t1n/auth/connect/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=client_credentials&client_id=33c563e7-6c91-4a9f-9d2eefbab40f5b58&client_secret=test1234"

You need to replace novus.zylinc.cloud/t1n with the base path of your Zylinc Cloud tenant.

The response contains the JWT access token. The token has no expiration date. To invalidate an issued token you need to change the Client ID and/or the Client Secret for the API client.

The token is used in subsequent calls to the API like this:

curl -H "Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia"
https://novus.zylinc.cloud/t1n/api/open/v1/some-endpoint

The sequence is illustrated below

Authorization Code Authentication

How to use User scope authentication.

To begin the authorization flow use a URL like the following example.

https://novus.zylinc.cloud/t1n/auth/connect/token
 ?response_type=code
 &client_id=openapi-oidc
 &redirect_uri=https%3A%2F%2Fexample-app.com%2Fcallback
 &scope=open-api.full_access

The code snippet below shows how to configure an ASP.NET web client for authentication against the Zylinc Open API in order to make a user-based authentication.

builder.Services.AddAuthentication(options =>
{
 options.DefaultScheme = "Cookies";
 options.DefaultChallengeScheme = "oidc";
}).AddCookie("Cookies")
 .AddOpenIdConnect("oidc", options =>
 {
 options.SignInScheme = "Cookies";
 options.Authority = "https://novus.zylinc.cloud/t1n/auth";
 options.ClientId = "openapi-oidc";
 options.ResponseType = "code";
 options.SaveTokens = true;
 options.TokenValidationParameters.ValidateAudience = true;
 options.UsePkce = true;
 options.Scope.Add("openid");
 options.Scope.Add("profile");
 options.Scope.Add("open-api.full_access");
 options.Scope.Add("offline_access");
 });

NOTE: When using the Authorization Code flow the Client ID must be set to "openapi-oidc", regardless of what is configured in Configuration Manager.

The access the Open API the JWT bearer token must have this scope: "open-api.full_access".

The authority must be set to the URL of the authentication service in your Zylinc Cloud tenant. It must have this format:

https://[TenantBasePath]/auth

where TenantBasePath is the domain and base path of your Zylinc Cloud tenant, for example novus.zylinc.cloud/t1n.

If you want to use a JavaScript based client you can use the Microsoft Authentication Library for JavaScript (MSAL.js) 

(https://learn.microsoft.com/en-us/javascript/api/overview/msal-overview?view=msal-js-latest) for getting an access token.

A Microsoft node.js sample that uses this library and Authorization Code flow with PKCE is available here https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-nodesamples/auth-code-pkce/README.md

Change the sample config to this

const config = {
 auth: {
 clientId: "openapi-oidc",
 authority: "https://novus.zylinc.cloud/t1n/auth",
 },
};

API Data Types

The public data types used in the API are available in a contracts class library distributed as a NuGet package called Zylinc.Api.Open.Contracts for use by C# clients. The NuGet package is available from this feed URL:

https://pkgs.dev.azure.com/ZylincExternal/9a24e13d-b035-450a-9ec7- c3d4a0f5f461/_packaging/ZylincPublicFeed/nuget/v3/index.json

Note that enum types are serialized as strings.

Swagger

The API is documented, and can be tested, using Swagger.

The Swagger URL is https://[TenantBasePath]/api/open/swagger.

API Endpoints

Callbacks

Order Callback

The Order Callback endpoint is used to order a callback to an external phone number. The callback order is placed in a Zylinc Cloud queue identified by its Queue ID.

The relative endpoint path is api/open/v1/contactcenter/callbacks This endpoint requires application level authentication.

The endpoint is called by an HTTP POST request with request parameters in the body in JSON format. The phone number must be entered in E.164 format.

The queue that is handling the callback must have a callback configuration, and the callback configuration must be enabled.

An optional name and callback time in UTC can also be specified.

Example Order Callback request using curl

curl -X 'POST' \
 'https://novus.zylinc.cloud/t1n/api/open/v1/contactcenter/callbacks' \
 -H 'accept: */*' \
 -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6I' \
 -H 'Content-Type: application/json' \
 -d '{
 "QueueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "PhoneNumber": "+4570223344",
 "Name": "John Doe"
}'

JavaScript Code Example

The JavaScript code below shows how to get an access token and call the API to order a callback.

// Get an access token from the Zylinc Cloud authentication service
var my_client_id = "enter your client id here";
var my_client_secret = "enter your client secret here";
fetch('https://novus.zylinc.cloud/t1n/auth/connect/token', {
 method: 'POST',
 body: 'grant_type=client_credentials&client_id=' + my_client_id +
'&client_secret=' + my_client_secret,
 headers: {
 'Content-Type': 'application/x-www-form-urlencoded'
 }
}).then(function (resp) {
 console.log("Token acquired");
 // Return the response as JSON
 return resp.json();
}).then(function (data) {
 // Call the API using the token we received for authentication
 return
fetch('https://novus.zylinc.cloud/t1n/api/open/v1/contactcenter/callbacks', {
 method: 'POST',
 headers: {'Authorization': 'Bearer ' + data.access_token,
 'Content-Type': 'application/json'
 },
 body: JSON.stringify({ QueueId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
PhoneNumber: "+4570232328" })
 });
}).then(function (data) {
 console.log("Response = ", data);
}).catch(function (err) {
 // Log any errors
 console.log('Something went wrong', err);
});

Conversations

Get all conversations

This endpoint is used to get all conversations. The relative endpoint path is api/open/v1/contactcenter/conversations This endpoint requires application level authentication.

 Get conversations owned by caller 

This endpoint is used to get conversations owned by the user calling this endpoint. The relative endpoint path is api/open/v1/contactcenter/conversations/me This endpoint requires user level authentication. 

Accept Conversation 

The Accept Conversation endpoint is used to accept a pending conversation. The relative endpoint path is api/open/v1/contactcenter/conversations/{conversationId}/accept The conversation ID can be extracted from webhook events. This endpoint requires user level authentication, and the user must also be logged in in the Web Agent as an agent. 

Transfer Conversation The Transfer Conversation endpoint is used to transfer a conversation to a target phone number. The relative endpoint path is api/open/v1/contactcenter/conversations/{conversationId}/transfer The conversation ID can be extracted from webhook events. This endpoint requires user level authentication, and the user must also be logged in in the Web Agent as an agent. 

End Conversation

The End Conversation endpoint is used to end a conversation. The relative endpoint path is api/open/v1/contactcenter/conversations/{conversationId}/end The conversation ID can be extracted from webhook events. This endpoint requires user level authentication, and the user must also be logged in in the Web Agent as an agent. 

 

Get Transcriptions

The Get Transcriptions endpoint is used to retrieve all transcriptions created since a specific date and time (in UTC).

The relative endpoint path is api/open/v1/contactcenter/conversations/transcriptions

This endpoint allows you to filter the results and control the amount of detail returned by using the following query parameters:

  • sinceUtc (required, DateTime): The earliest UTC date and time for transcriptions to include.
  • maxItems (optional, int, default: 100): The maximum number of transcriptions to return. If you request
    transcription text or summary, the maximum is 100; otherwise, up to 4000. 
  • searchByCreationDate (optional, bool, default: false): If true, filters by the transcription's creation time; if
    false, filters by the recording's start time. 
  • includeTranscriptionText (optional, bool, default: true): If true, includes the full transcription text in the
    response. includeSummary (optional, bool, default: true): If true, 
  • includes a summary of the transcription in the
    response.

This endpoint requires application level authentication. 

Get Transcription

The Get Transcription endpoint is used to retrieve a transcription for a specific recording. The relative endpoint path is api/open/v1/contactcenter/conversations/{conversationId}/transcription The conversation ID can be extracted from webhook events. This endpoint requires application level authentication.

Dial

The Dial endpoint is used to dial a phone number. 

The relative endpoint path is api/open/v1/contactcenter/dial 

The conversation ID can be extracted from webhook events. 

This endpoint requires user level authentication, and the user must also be logged in in the Web Agent as an agent. 

This endpoint can be used to implement a "Click-to-dial" feature. 

Users

Users can be looked up either by email address or by phone number. The relative endpoint paths are 

  • api/open/v1/users/email 
  • api/open/v1/users/emails 
  • api/open/v1/users/phonenumber 
  • api/open/v1/users/phonenumbers 

These endpoints require application level authentication. Phone numbers can be specified with or without a country code prefix (e.g. "+45" for Denmark). 

Agent sessions

Get all agent sessions 

This endpoint is used to get all agent sessions. The relative endpoint path is api/open/v1/contactcenter/agent sessions 

This endpoint requires application level authentication. 

Get agent sessions owned by caller 

This endpoint is used to get agent sessions owned by the user calling this endpoint. 

The relative endpoint path is api/open/v1/contactcenter/agentsessions/me 

This endpoint requires user level authentication. 

Presence

Get presence of users 

The current presence state of users can be read. Users are identified by their unique ID in Zylinc Cloud. 

This ID can be acquired by a user lookup on email. 

The relative endpoint path is api/open/v1/presence 

This endpoint requires application level authentication

Set presence

The presence state of the user calling the endpoint can be set. The relative endpoint path is api/open/v1/presence/me This endpoint requires user level authentication. Presence set via the Open API has the category "Third party" in Zylinc Cloud.

Set presence subscription

Presence subscriptions can be created and deleted from the Open API. Presence changes will be sent via webhook and SignalR. The relative endpoint path is api/open/v1/presence/subscribe This endpoint requires user level authentication. Users to subscribe to presence for are identified by their IDs, which can be found by user lookup on email. If no user IDs are given all presence subscriptions are deleted.

Navigator Time Registration

Export of Navigator Time Registration calls can be done using the Open API. The relative endpoint path is api/open/v1/navigator/timeregistration This endpoint requires application level authentication. The endpoint is called by an HTTP GET request with request query parameters denoting export format and file format.

Versions

The API has these unprotected endpoints (no authentication required) for getting version information 

  • API version - returns the version of the API. 
  • Service version - returns the assembly version of the Open API service. 
  • Contracts version - returns the assembly version of the Open API contracts library. 
  • Product version - returns the version of the Zylinc Cloud product.

Receiving Events

Events can be pushed to clients using either webhook callbacks and/or via SignalR (a websocket).

Webhook

Zylinc Cloud is able to push events to Open API clients by calling a public webhook endpoint exposed by an Open API client.

The URL of the webhook is specified in the Configuration Manager web application in Zylinc Cloud under the section Zylinc Open API. For each API client you can specify an optional webhook URL. If a valid webhook URL is entered the Open API service will push events to the API client by making HTTP POST requests to the webhook endpoint.

These are the requirements to the webhook endpoint implementation:

  1. The webhook URL must use SSL and have a valid SSL certificate.
  2. The webhook URL must be public reachable from the internet on port 443.
  3. A GET request to the endpoint must return the Client ID as a string in the response body and return with HTTP status code 200 OK within a timeout of 10 seconds.
  4. A POST request to the endpoint must return HTTP status code 200 OK within a timeout of 10 seconds.

Notes

  • Delivery of events to the endpoint is not guaranteed. If a POST request fails it is not retried.
  • Your webhook endpoint must reply as fast as possible so it does not block the caller.
  • The timeout for POST requests to your webhook is 10 seconds.
  • Your webhook endpoint is validated every 30 minutes. If your webhook endpoint does not meet the requirements above POSTs to the endpoint will be suspended until next validation (i.e. up to 30 minutes).

Webhook Events

Events are pushed to the webhook in an HTTP POST request with a body containing this C# event class encoded as JSON

namespace Zylinc.Api.Open.Contracts.V1.WebhookEvents
{
 /// <summary>
 /// Generic webhook event container.
 /// This is the type of object that is posted to webhook event receivers.
 /// </summary>
 public class WebhookEvent
 {
 /// <summary>
 /// Unique sender ID. 
 /// This is the Novus customer ID.
 /// </summary>
 public Guid SenderId { get; }
 /// <summary>
 /// API version, for example "v1"
 /// </summary>
 public string ApiVersion { get; 
 /// <summary>
 /// The type of event stored in <see cref="EventObject"/>.
 /// Use this type information to deserialize <see cref="EventObject"/>
from JSON into the actual event object.
 /// </summary>
 public WebhookEventType EventType { get; }
 /// <summary>
 /// Event object. The actual type is specified in <see cref="EventType"/>.
 /// </summary>
 public object EventObject { get; }
 /// <summary>
 /// Constructor that constructs an immutable object instance.
 /// </summary>
 public WebhookEvent(Guid senderId, string apiVersion, WebhookEventType
eventType, object eventObject)
 {
 SenderId = senderId;
 ApiVersion = apiVersion;
 EventType = eventType;
 EventObject = eventObject;
 }
 }

Below is an example POST request body in JSON format

 

{
 "SenderId": "7d285b35-ccf2-4c4f-b5a7-7a95654e4e38",
 "ApiVersion": "v1",
 "EventType": "ConversationEvent",
 "EventObject": {
 "Conversation": {
 "Id": "733c1a13-2e21-4f8a-a494-b66288a03abf",
 "InitiationTimeUtc": "2022-06-28T10:56:31.320492Z",
 "ConversationState": "Queued",
 "Direction": "Incoming",
 "AgentDetails": null,
 "QueueDetails": null,
 "Originator": {
 "Id": "66940d31-5be5-4480-ba6c-bceb28940baa",
 "Endpoint": {
 "AddressType": "PhoneNumber",
 "Address": "70203040",
 "Platform": "Cisco"
 },
 "JoinedConversationTimeUtc": "2022-06-28T10:56:31.3204924Z"
 },
 "Participants": []
 }
 }
}

Webhook Event types

The following event types are sent via webhook

  • ConversationEvent
  • AgentEvent
  • UnifiedPresenceEvent
  • TranscriptionEvent

The event data types are documented as C# class in an API Contracts NuGet package that you can get from Zylinc.

A Conversation object has these properties

Property C# Datatype Description
Id Guid Unique identifier of the conversation
InitiationTimeUtc DateTime The time in UTC when the conversation was initiated
EndTimeUtc DateTime? The time in UTC when the conversation was ended. If null, the conversation has not yet ended.
ConversationState Enum The current state of the conversation (Queued / Processing / Connected)
Direction Enum The conversation direction (Incoming / Outgoing)
AgentDetails object Details about the agent that controls this conversation
QueueDetails object The current/last queue details the conversation is associated with
Originator object The conversation originator
Participants object collection The participants in the conversation
CollectedDigits string? String containing digits collected in for example IVR prompts 

A Transcription object has these properties

Property C# Datatype Description
EndTimeUtc DateTime The time in UTC when the recording of the conversation ended
Language Enum The Language of the conversation
FirstAgent object? The Id, DisplayName and Email address of the last agent that was bridged with the conversation. If null, then the conversation was never answered by an agent. Will occur if the conversation was transferred to an external number.
CollectedDigits string? The digits pressed by the customer before entering a queue
NetPromoterScore object? Net Promoter Score information containing the score given by the agent and the score, comment and category given by the customer
TranscriptionText string The plain text transcription of the entire conversation including timespans for when in the conversation each sentence as spoken
Summary string A Summary of the transcription

SignalR

A SignalR endpoint is exposed at this URL

https://[TenantBasePath]/api/open/hubs/v1/notifications

where TenantBasePath is the path of your Zylinc Cloud tenant, for example novus.zylinc.cloud/t1n.

Authentication

The SignalR endpoint requires user authentication with a bearer token, like other API endpoints. The access token needs to be added as a query parameter in the SignalR connection URL.

Javascript Example

The Javascript code snippet below shows how to connect to SignalR and receive the three message types:

var signalrconnection = new signalR.HubConnectionBuilder()
 .withUrl("https://novus.zylinc.cloud/t1n/api/open/hubs/v1/notifications?
access_token=Bearer%20eyJhbGciOiJSUzI1NiI...YnMK6LKJ3u")
 .build();
signalrconnection.on("ReceiveAgentEvent", function (agentEvent) {
 console.log("agentEvent received");
});
signalrconnection.on("ReceiveConversationEvent", function (conversationEvent) {
 console.log("conversationEvent received");
});
signalrconnection.on("ReceiveUnifiedPresenceEvent", function
(unifiedPresenceEvent) {
 console.log("UnifiedPresenceEvent received");
});
signalrconnection.start();

See also the Microsoft documentation on how to create a SignalR client in Javascript

https://learn.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-7.0&tabs=visual-studio

CORS

The domain from which you connect to SignalR must be added as an allowed CORS origin. This is done in the Open API client definition in Configuration Manager.

SignalR Event Types

The following event types are sent via SignalR

  • ConversationEvent
  • AgentEvent
  • UnifiedPresenceEvent

The event data types are documented as C# class in an API Contracts NuGet package that you can get from Zylinc.

SignalR Event Filtering

When a SignalR connection is established the access token identifies the connecting user. The user's ID is used to filter events sent via SignalR according to these rules:

  • A conversation's agent ID matches the SignalR user's ID.
  • An agent event's agent ID matches the SignalR user's ID.
  • A presence event's user ID matches the SignalR user's ID.