Skip to content

Synergy SKY CONNECT OVI

Copyright Copyright © Synergy SKY AS

Welcome

Welcome to the Synergy SKY Connect Open Video Interop documentation! This guide will help you get started with our powerful REST API and JavaScript framework, designed to simplify video conferencing interoperability.

What is Synergy SKY Connect?

Synergy SKY Connect is a multi-vendor gateway that bridges the gap between traditional SIP video conferencing endpoints and modern cloud-based meeting/video platforms like Microsoft Teams, Google Meet, and Zoom. It provides a seamless, one-click-to-join experience from any SIP device, regardless of the meeting platform. Our solutions ensure that all your video conferencing equipment can work together, streamlining workflows and maximizing your existing technology investments.

Introduction to Open Video Interop (OVI)

Open Video Interop (OVI) is the open standard from Synergy SKY that connects the world of modern web-based video apps with the global ecosystem of SIP video devices and conferencing rooms.

How it Works

At its core, OVI works like a SIP ↔ WebRTC Enabled WebApp gateway — but it’s designed as a developer integration point, not just a protocol bridge.

By integrating once with OVI, web app developers can make their video platforms instantly accessible from millions of SIP endpoints (Cisco, Poly, Lifesize, Yealink, Zoom Rooms and more) without needing to implement SIP themselves.

For enterprises, OVI means your existing room systems gain seamless access to any new or emerging video app. For developers, it means your web application can reach the enterprise video hardware market with minimal effort. In short: OVI removes the barriers between SIP and WebRTC, enabling universal interoperability and future-proof collaboration.

Key Features

  • Universal Compatibility: OVI is an open standard designed to work with all major web-based video services and SIP hardware, ensuring future-proof integration.

  • Enhanced Interoperability: OVI enhances interoperability, allowing companies to integrate existing SIP hardware with modern cloud-based collaboration tools. This expands the usability of their meeting rooms, freeing them from the limitations of proprietary systems.

The interfaces

OVI High-level

OVI CONNECT API

Our REST API is the starting point of the OVI solution and is where you provision the URL to the collaboration session you want to enable for SIP video. Typically this is executed from your backend.
A simple REST API will allow you to publish your URL and in return you will be given a SIP-URI which can be dialed directly from any SIP enabled video conferencing devices that are allowed to dial out on the internet.

OVI JavaScript Framework

The OVI JavaScript Framework is an API that enables your WebRTC-enabled web app to integrate with Synergy SKY CONNECT. When a user dials your SIP-URI from the OVI CONNECT API, Synergy SKY CONNECT automatically launches a browser session to your web app, providing access to the framework for seamless call handling.

OVI CONNECT API

OVI API Getting Started

Getting started

To get started with the OVI API, you need to aquire credentials for logging in. Please get in touch with us thru contact@synergysky.com.

High-level overview

The OVI CONNECT API is a very simplistic REST like API thats sole purpose is to expose methods for adding and/or removing scheduled sessions that maps your selected URL to a URI.

Thru the available endpoints, you can save or bulk-save up to batches of 1000.

---
config:
  layout: elk
  look: classic
  theme: 'forest'
---
sequenceDiagram
    autonumber
    participant wabe as WebApp Backend
    participant api as CONNECT API
    wabe->>+api: auth/gettoken
    api->>-wabe: Bearer token
    wabe->>+api: /save or /bulksave (URL to SIP-URI provisioning)
    api->>-wabe: get object id and SIP-URI
    wabe-->>api: update by using object id

OVI API Reference

General Information

Documentation for CONNECT API/PAPI v3 provisioning web service.

The base path for the API is: api/provisioning

The path api/provisioning version 3.0 has three endpoints /save, /bulksave, /delete

All requests need included header Authorization: Bearer <acquired token> and x-api-version: 3.0

How to aquire Bearer token

Request

To aquire Bearer token we need to POST correct authentication information to auth/gettoken

in the header following

following object needs to be included in body of the POST 

{
  "TenantId": "<uuid>",
  "ClientSecret": "<secret...>"
}

Response

a string with the token to be used in the header of all API requests. 

"magic_long_token"

API Endpoints

POST [base]/save

Will provision/insert a new gateway if input.GatewayId is null. The GatewayId that the gateway has will be returned, so that it is possible to update this gateway next time instead of creating a duplicate.

If GatewayId is sent, the existing gateway will be updated. We prefer that you send GatewayId when you have it.

Note

After 30 days without any interaction, the URL to SIP-URI mapping will be automatically deleted. To keep the mapping, you need to set up a process to continuously refresh the object.

Examples

Request

without GatewayId 

{
  "GatewayId": null,
  "PlannedStartAtUtc": "2025-03-20T10:00:00.000Z",
  "PlannedEndAtUtc": "2025-03-20T11:30:00.000Z",
  "MeetingTypeIdentifier": "OVI",
  "MeetingUrl": "https://yourvideoplatform.com/meet-now/325dagxgy",
  "MeetingId": "325dagxgy",
  "MeetingPassword": "password123",
  "IsExternalOrganizer": false,
  "LiveCaptionsEnabled": true
}

with GatewayId 

{
  "GatewayId": "0195b8c8-3fd2-787d-a73b-bfe03f5e5ff5",
  "PlannedStartAtUtc": "2025-03-20T10:00:00.000Z",
  "PlannedEndAtUtc": "2025-03-20T11:30:00.000Z",
  "MeetingTypeIdentifier": "OVI",
  "MeetingUrl": "https://yourvideoplatform.com/meet-now/325dagxgy",
  "MeetingId": "325dagxgy",
  "MeetingPassword": "password123",
  "IsExternalOrganizer": false,
  "LiveCaptionsEnabled": true
}

Response
{
  "GatewayId": "0195b8c8-3fd2-787d-a73b-bfe03f5e5ff5",
  "EndpointDialUri": "t.ab123.thb14b7@qa.joingw.com",
  "CommonDialUri": "t.123456789012@joingw.com"
}

POST [base]/bulksave

Bulk Provisioning This feature allows for the provisioning of up to 1,000 gateways in a single call. Each item in the bulk request uses the same data structure as a standard save call, with the addition of one property: BulkItemId.

  • With BulkItemId: If you provide a BulkItemId in your request, you can use it to match each item in the response, which will also include the corresponding HTTP status for that item.
  • Without BulkItemId: If BulkItemId is not set in the input, you can still identify each item in the response by its sequence. The first item in the request corresponds to the first item in the response, the second to the second, and so on.

Examples

Request
[
  {
    "BulkItemId": "item-123",
    "GatewayId": null,
    "PlannedStartAtUtc": "2025-03-20T10:00:00.000Z",
    "PlannedEndAtUtc": "2025-03-20T11:30:00.000Z",
    "MeetingTypeIdentifier": "OVI",
    "MeetingUrl": "https://yourvideoplatform.com/meet-now/325dagxgy",
    "MeetingId": "325dagxgy",
    "MeetingPassword": "password123",
    "IsExternalOrganizer": false,
    "LiveCaptionsEnabled": true
  },
  {
    "BulkItemId": null,
    "GatewayId": "0195ae46-3aad-79f5-9c1e-65609ea809a3",
    "PlannedStartAtUtc": "2025-03-21T13:00:00.000Z",
    "PlannedEndAtUtc": null,
    "MeetingTypeIdentifier": "OVI",
    "MeetingUrl": "https://yourvideoplatform.com/meet-now/53abacgi",
    "MeetingId": "53abacgi",
    "MeetingPassword": "123pass",
    "IsExternalOrganizer": true,
    "LiveCaptionsEnabled": false
  }
]
Response
[
  {
    "BulkItemId": "item-123",
    "StatusCode": 200,
    "StatusDescription": null,
    "GatewayId": "0195b8d3-a100-72eb-a0ee-411171ec8345",
    "EndpointDialUri": "t.ab123.1a2b3cD@joingw.com",
    "CommonDialUri": "t.12345678@joingw.com"
  },
  {
    "BulkItemId": "item-789",
    "StatusCode": 400,
    "StatusDescription": "Validation failed: \n-- PlannedEndAtUtc: 'Planned End At Utc' can not be before PlannedStartAtUtc. Severity: Error",
    "GatewayId": null,
    "EndpointDialUri": null,
    "CommonDialUri": null
  }
]

DELETE [base]/delete

Takes in a gatewayId, and will delete this if it exists, and returns HttpStatus Ok (200). If gatewayId does not exist, no error will be thrown, since it then is considered already deleted.

OVI JS Framework

OVI Framework Getting Started

Getting started

To start developing with the OVI, you can aquire the synergysky_ovi.js header file which you can include at the top of your WebApp. 

<script 
    src="https://synergysky.github.io/ovi/sdk/synergysky_ovi.js">
</script>
The header file will act as a off-line MOCK that allows you to simulate the CONNECT interface.

A video platform WebApp example can be viewed and copied here https://synergysky.github.io/ovi/example/example.html

Warning

Remember to remove the synergysky_ovi.js script before deploying your application for testing on the CONNECT platform. If you fail to remove the script, your web app will not work correctly.

How does it work?

First you have to provision your application URL to the OVI CONNECT API and retrive your SIP-URI. Second you will dial the given SIP-URI from your video conference endpoint.

Once the call reaches Synergy SKY CONNECT, our system opens a new browser session that loads your web app. This browser environment exposes the OVI JavaScript framework/API. You can verify the environment by querying for the synergysky JavaScript interface, confirming that the framework is available and ready for use.

From now on Synergy SKY CONNECT expect your WebApp to follow the implementation defined by OVI. Most WebApp needs minimal modification to work with OVI due to the fact that we behave like a normal user. 

---
config:
  layout: elk
  look: classic
  theme: 'forest'
---
sequenceDiagram
    autonumber
    participant vc as Video Conference Device
    participant connect as CONNECT
    participant web as WebApp implementing OVI
    vc->>+connect: Calling the SIP-URI (from OVI CONNECT API)
    connect->>-web: Launch your WebApp with OVI Framework injected

    vc-->>+connect: Interact with DTMF during call
    connect-->>-web: send CallerInteraction event to WebApp

    vc-->>+connect: Start sharing presentation on second stream
    connect-->>+web: send GetDisplayMedia event to WebApp
    web-->>-web: WebApp calls navigator.mediaDevices.getDisplayMedia()

    web-->>+connect: execute from WebApp: synergysky.endSession()
    connect-->>-vc: Send SIP BYE

OVI Framework Reference

When connect loads up your webapp the following documented API will be available for you to utilize. In an offline dev-scenario inserting the synergysky_ovi.js at the top of the webapp will enable the same API, with mocked behaviour.

Interfaces

synergysky

The synergysky interface of OVI is available inside a connect session (or in simulation by including synergysky_ovi.js in the header of your code).

navigator.mediaDevices

The navigator.mediaDevices interface is the Media Capture and Streams API that provides access to connected media input devices like cameras and microphones, as well as screen sharing. In essence, it lets you obtain access to any hardware source of media data. However when in a CONNECT session parts of the Instance methods are overridden.

Instance properties

synergysky.SupportedVersions

The synergysky.SupportedVersions is a read-only property that provides a list of available version strings.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
try
{
  if (synergysky.SupportedVersions.includes("2.0"))
  {
    synergysky.startSession("2.0", "my-orgs-integration-key");
  }
  else
  {
    synergysky.startSession("1.0", "my-orgs-integration-key");
  }
}
catch (e) 
{
  console.log(e); // Logs the error
}

synergysky.GetDisplayMediaEventTypes

synergysky.GetDisplayMediaEventTypes is a JSON object with properties that act as enums for improved coding. They all translate to strings but ensure type safety.

synergysky.GetDisplayMediaEventTypes = 
{
  "READY": "ready", // (1)
  "STOPPED": "stopped" // (2)
}
1. An event emitted when the second stream inside navigator.mediaDevices.getDisplayMedia() becomes available, typically when a presentation or sharing is started on the connected video conferencing device. 2. An event emitted when the second stream from the video conference unit is stopped.

synergysky.CallerEndedSessionEventTypes

synergysky.CallerEndedSessionEventTypes is a JSON object with properties that act as enums for improved coding. They all translate to strings but ensure type safety. When an event of a similar name is emitted, it will use the properties from this object to simplify type-safe code.

synergysky.CallerEndedSessionEventTypes = 
{
  CALLER_HANGUP: "caller_hangup", // (1)
}
1. An event emitted when the video conference unit hangs up the call.

Example

1
2
3
4
5
6
7
synergysky.addEventHandler("CallerEndedSession", async (event, action) => 
{
    if (action == synergysky.CallerEndedSessionEventTypes.CALLER_HANGUP)
    {
      sayGoodbyeAndTerminateOurWebApp();
    }
});

Instance methods

synergysky.startSession()

The synergysky.startSession() method of the synergysky interface needs to be called at the start of the session to establish API version in use aswell as integration key.

Warning

The other methods in the API will not be available until startSession is executed successfully.

Syntax

1
await synergysky.startSession(version_string, integrationKey_string)
Parameters
version_string
a string containing the version you are integration, currently there are only one. A list of supported versions are available in synergysky.SupportedVersions property. Available string constants for versions are available in synergysky.Versions property.
integrationKey_string
a string containing the integration key, without properly validated key, the API will throw error on engagement and malfunction. When using the synergysky_ovi.js simulation header, any value is accepted.
Return value

None

Is Throwing

This function will throw on error.

Example
1
2
3
4
5
6
7
8
try
{
  await synergysky.startSession(version_string, integrationKey_string)
} 
catch (e)
{
  // No point moving on from here
}

synergysky.endSession()

The synergysky.endSession() method of the synergysky interface is used to terminate the session in connect, which will leads to connect sending a SIP BYE to the calling video conference endpoint, and eventually destroy the web-session.

Syntax

1
synergysky.endSession()
Parameters

None

Return value

None

Is Throwing

This function will not throw on error.

synergysky.getCallerInfo()

The synergysky.getCallerInfo() method of the synergysky interface is used for getting a read-only object of session data.

Syntax

1
synergysky.getCallerInfo()
Parameters

None

Return value

The method will return a json object with following structure 

{
  RemoteURI: "meetingroom@customer.com",
  DisplayName: "Meeting Room",
  DialedURI: "o.acme@joingw.com",
  DualScreen: true,
  GatewayCallActivityId: "<guid>"
}

Is Throwing

This function will not throw on error.

Example
1
console.log(synergysky.getCallerInfo().DisplayName);

synergysky.addEventHandler()

The synergysky.addEventHandler() method of the synergysky interface is used for setting up eventhandlers that allows the OVI API to notify implemented code about various events.

see: Events

Syntax

1
synergysky.addEventHandler(event_name_string, async (event_object, action_string) = > { });
Parameters
event_name_string
a string containing the kind of event you want to listen to (see: Events)
async (event_object, action_string) = > { }
either a function or lambda with the signature of async (event_object, action_string)
event_object
The event_object type is a read-only object containing timestamp for spawned action aswell as event type, to allow for using same function on multiple events. 
{
   "EventType": "CallerInteraction",
   "TimeStamp": "2025-09-09T11:10:03.397Z"
}
action_string
The action string depends on type of event but would typically be a string constant, or if interaction the DTMF code typed on the remote video conferencing device.

See Instance properties

Return value

None

Is Throwing

This function will throw on error.

synergysky.removeEventHandler()

The synergysky.removeEventHandler() method of the synergysky interface is used for removing attached eventhandlers.

see: Events

Syntax

1
synergysky.removeEventHandler(event_name_string);
Parameters
event_name_string
a string containing the kind of event you want to listen to (see: Events)
Return value

None

Is Throwing

This function will throw on error.

synergysky.startSendSecondaryStream() ( not in use )

For future use, not implemented yet.

synergysky.stopSendSecondaryStream() ( not in use )

For future use, not implemented yet.

navigator.mediaDevices.getUserMedia()

This is an overloaded MediaDevices API, and will present the video conferencing device remote camera and microphone. For more details on the API see MediaDevices: getUserMedia() method

navigator.mediaDevices.getDisplayMedia()

This is an overloaded MediaDevices API, and will present the second remote video stream going out from the video conferencing device. Due to the nature of video conferencing devices and the ability to turn on and off the secondary screen, the availability of this stream is notified thru the GetDisplayMedia event handler.

For more details on the official API see MediaDevices: getDisplayMedia() method

see: GetDisplayMediaEventTypes and addEventHandler

navigator.mediaDevices.enumerateDevices()

This is an overloaded MediaDevices API, and will present the available devices in the connect call. For more details on the API see MediaDevices: enumerateDevices() method

Events

GetDisplayMedia

The GetDisplayMedia event is fired when a new change to the stream behind navigator.mediaDevices.getDisplayMedia() is changed

This event is not cancelable and does not bubble.

Syntax

1
synergysky.addEventHandler("GetDisplayMedia", async (event_object, action_string) = > { });
Parameters
event_object
a string containing the kind of event you want to listen to (see: Events)
action_string
The emitted action, see: GetDisplayMediaEventTypes

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
window.synergysky.addEventHandler("GetDisplayMedia",
  async (event, action) =>
  {
    if (action == synergysky.GetDisplayMediaEventTypes.READY)
    {
      const secondStream = await navigator.mediaDevices.getDisplayMedia({ video: true });
      const video = document.getElementById('sharescreen');
      video.srcObject = secondStream;
    }
    else if (action == synergysky.GetDisplayMediaEventTypes.STOPPED)
    {
      const video = document.getElementById('sharescreen');
      video.srcObject = null;
    }
  });

CallerInteraction

The CallerInteraction event is fired when the video conferencing device sends DTMF tones.

This event is not cancelable and does not bubble.

Syntax

1
synergysky.addEventHandler("CallerInteraction", async (event_object, action_string) = > { });
Parameters
event_object
a string containing the kind of event you want to listen to (see: Events)
action_string
The emitted DTMF code
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
synergysky.addEventHandler("CallerInteraction", async (event_object, action_string) = > 
    { 
      switch (action)
      {
        case "6*":
          await advanceSlide(); // i.e. advance slide embedded in the webapp
          break;
        case "5":
          await readyToTalk(); // i.e. notify the webapp that we are now ready to talk.
          break;
        default:
          console.log("Unhandled interaction from video conference unit");
      }
    });

CallerEndedSession

The CallerEndedSession event is fired when the video conferencing device terminates/hangs-up the call on their side

This event is not cancelable and does not bubble.

Syntax

1
synergysky.addEventHandler("CallerEndedSession", async (event_object, action_string) = > { });
Parameters
event_object
a string containing the kind of event you want to listen to (see: Events)
action_string
The emitted action, see: CallerEndedSessionTypes
Example
1
2
3
4
5
6
7
synergysky.addEventHandler("CallerEndedSession", async (event_object, action_string) = > 
    { 
      if (action_string == synergysky.CallerEndedSessionEventTypes.CALLER_HANGUP)
      {
        sayByeToWebApp();
      }
    });

Other

Setting up Linphone as a SIP "endpoint"

Intro

To be able to test out OVI functionality during development, a SIP capable endpoint device is required - like a conference system (HP/Poly, Cisco, LifeSize, Yealink, etc.) or you can use your PC with a SIP application like Linphone

This guide will help you setup Linphone, towards Synegy SKY Registrar.

Setting up

Download and install linphone, i would recommend the Version 6.0 "Call Edition"

Link to their download page

Download Page

STEP 1: Start the App Screen 1 Skip the wizard

Screen 2 Setup provisioning

Screen 3 Fill in the URL: https://ladybug.higen.org/config.xml

Note

This will provide an XML with a Synergy SKY SIP trial account

After this step the app will automatically restart, sometimes it ends up in the wizard again in that case, restart the appelication

Screen 4

Go into the applications settings

Screen 5

Select "Advanced Parameters" and ensure that

  • H264 is ON
  • VP8 is OFF
  • AV1 is OFF

Screen 6

Exit the settings and do a test call to the URI

o.test@qa.joingw.com

Screen 7

Your client is ready