Skip to content

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

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.

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

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

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();
      }
    });