Partners Blog Contact Us

Overview of VidyoEngage for Genesys



The VidyoEngage for Genesys Adapter provides video conferencing to the Genesys solution by integrating with Vidyo. Agents using the Workspace Desktop Edition (Workspace) can escalate voice and chat interactions to a video conference with customers. In addition, customers can use the click-to-Vidyo capability to initiate a video conference with a Workspace agent.

Use Cases

The types of interactions that customers may use with the VidyoEngage for Genesys Adapter include the following:

  • Voice interactions
  • Web chat interactions
  • New Vidyo interactions

Voice to Vidyo Escalation

A customer in an active voice interaction may receive a guest link from an agent to join a video conference.  The agent may share the guest link in the following ways:

  1. Conversation
  2. Email
  3. SMS

Web Chat to Vidyo Escalation

A customer in an active web chat interaction may join a video conference in two ways:

  1. Customer may request a video conference.
    Assumes that the customer user interface has a button to send a request message to the VidyoEngage for Genesys framework in order to join the video conference.

  2. Agent may offer a video conference.
    Assumes that the customer user interface can receive a message from the VidyoEngage for Genesys framework in order to join the video conference.


A customer may request a video conference that VidyoEngage for Genesys processes as a new Vidyo interaction. This assumes that the customer user interface has a button to send a request message to the VidyoEngage for Genesys framework.



The VidyoEngage for Genesys Adapter solution is composed from:

  • The VidyoWorks Platform, serving Vidyo sessions between Genesys agents and customers.
  • Web Applications, which are customer-side web widgets. Customer can send Vidyo session requests through them.
  • The Genesys Framework, which is the Genesys interaction routing and reporting suite.
    This includes the Vidyo Server, which is the signaling interface between the Web Widgets and Genesys Framework.
  • The Workspace Desktop edition, which is a thick agent desktop integrated with the Vidyo Platform. Genesys agents use this desktop to communicate with customers and establish Vidyo sessions.
  • Vidyo Recording, which is the Vidyo recorder. It can be optionally enabled for Vidyo session recording.


Components and Functionality

The VidyoEngage for Genesys Adapter contains the following components:

  • Customer-side component (Web Container and Web Widgets) to manage the Customer Vidyo communication interface to the VidyoEngage for Genesys Framework
  • A VidyoEngage for Genesys framework component to manage the new Vidyo interaction type for Click-to-Vidyo and for the agent use of the video conference.

Customer-side Components

The solution contains Sample integration widgets. The widgets can be deployed to Web Container and used to help customers with the Vidyo integration.

Sample widgets provide the following integrations:

  • Sample standalone widgets
    • Click to Vidyo (REST)
    • Click to Vidyo (REST Simple)
    • Click to Vidyo (Websocket)
    • Chat to Vidyo (WEB-API)
    • >Standalone Vidyo client based on Chat To Vidyo (ve4gchat)

VidyoEngage for Genesys Framework Components

There are two subcomponents within the Genesys Framework that support the Adapter.  Vidyo Server is required for Click-to-Vidyo, whereas the Workspace Plugin for Vidyo is required for the Adapter to support video conferencing.

Vidyo Server

The Vidyo Server supports Click-to-Vidyo by providing an interface that allows communication from the customer application to send a request to the Genesys Framework.  Vidyo Server initiates the creation of a new Vidyo interaction that the Genesys Framework routes to Workspace.  In addition, Vidyo Server receives a guest link from Workspace and forwards it to the customer application.

Although Vidyo Server does not directly support High Availability (HA) on the front end, the communication flow may be managed by either a software or hardware load balancer. The load balancer ensures that subsequent requests from the same client are sent to the same Vidyo Server instance.

On the back end, Vidyo Server does support HA to the Interaction Server to support a Primary and Backup Interaction Server in a Warm Standby configuration.

Vidyo Server can be standalone on a server or it can share a server with other Genesys components.

Workspace Plugin for Vidyo

The Workspace Plugin for Vidyo supports all of the Use Cases by allowing the Agent to create a video room and share its guest link with the customer applications via the Genesys Framework.  Workspace obtains Vidyo account credentials from Genesys Administrator (GA) configuration for authentication.  It interfaces with the VidyoClient library to control the local devices.  For video room creation and management, Workspace interfaces with the VidyoWorks platform.

Use Case Dependencies

The components required are dependent upon the use cases needed for the solution. 

In the diagram below:

  • Black text indicates foundation or prerequisite solutions
  • Red text indicates components needed for the VidyoEngage for Genesys Adapter solution to support the use case

Genesys Framework Components

The Genesys framework components included in deployment package are:

  • Vidyo Server: The deployment procedure is explained in the Deploying VidyoEngage for Genesys article.
  • VidyoApplications: Composer project that contains routing script for Vidyo interaction. For more information about routing customization, refer to the Genesys documentation.
  • ORSApp: Compiled routing application to be deployed to web container and configured in Genesys environment. Deployment is explained in the "ORS Tomcat" section of the Deploying VidyoEngage for Genesys article.

Genesys framework components are serving routing and signaling between customer side and Workspace desktop application integrated with vidyo client.

Workspace desktop application is handling the interaction receive and escalation mechanism. It is also rendering video frames for the vidyo session.


Connection Map

The Vidyo Server component is a web container communicating at http and https ports. These ports must be accessible from the customer widget web container for the Click to Vidyo scenario.

For the Chat to Vidyo scenario, the Vidyo Server is not required. The connection diagram is shown here:


Click to Vidyo Connection Map

Tomcat (Web Widget) VidyoServer <port> http

<port secured>

VidyoServer IXN <IXN port> TCP/IP
VidyoServer ORS

<ORS http port>


<IXN port>


<ORS http port>

WDE VidyoWorks <vidyo-url> <http/https>

Port descriptions:

  • <port>: Vidyo Server http port set in VidyoServer startup script
  • <port secured>: Vidyo https port set in VidyoServer startup script
  • <IXN port>: Interaction server port configured in GA
  • <ORS http port>: ORS http port configured in GA
  • <vidyo-url>: Access to Vidyo platform through Client API and REST User API


Adapter Interfaces and Flows

The Adapter solution interacts with Genesys and the VidyoWorks platform. The interfaces differ based on solution use case. The use cases are:

  • Voice to Vidyo
    • interface to Genesys
      • WDE client and Vidyo interaction view
    • interface to VidyoWorks
      • VidyoClient API
      • Vidyo User REST API
      • Vidyo web client in widget
  • Click to Vidyo
    • interface to Genesys
      • WDE client and Vidyo interaction view
      • WDE client and ORS integration
      • Vidyo Server, CFG server, IXN server and ORS interface
    • interface to VidyoWorks
      • VidyoClient API
      • Vidyo User REST API
      • Vidyo web client in widget
  • Chat to Vidyo
    • interface to Genesys
      • Web Sample Chat Widget interface to Genesys eServices WEB-API server
      • WDE client and Vidyo interaction view
      • WDE client and chat content handler
    • interface to VidyoWorks
      • VidyoClient API
      • Vidyo User REST API
      • Vidyo web client in widget

The high level diagrams in this section show what interfaces needs to be configured to make the adapter work.

Chat to Vidyo Flow (Simplified)

  1. Customer requests chat using Genesys WEB-API.

  2. Chat is created in chat server.

  3. Chat is delivered to an agent.

  4. Vidyo session is created at VidyoWorks platform from WDE and WDE gets meeting room URL.

  5. WDE sends meeting room URL through chat.

  6. Widget processes URL in chat message and uses thin client to join the meeting.

  7. Customer joins the meeting.


Click to Vidyo Flow (Simplified)

  1. Customer made Click to Vidyo request.

  2. ORS session is created.

  3. Genesys IXN server interaction is created.

  4. Interaction is delivered to an agent.

  5. Agent created meeting at VidyoWorks platform and WDE obtained meeting guest URL.

  6. Meeting URL is sent to ORS session.

  7. ORS updated Vidyo Server with Meeting URL.

  8. Vidyo Server notified Click to Vidyo application about meeting URL.

  9. Click to Vidyo web application started Vidyo thin client to join Vidyo session at VidyoWorks platform.

This simplified flow is valid for REST, REST Simple, and Websocket sample widgets.


Voice to Vidyo Flow (Simplified)

  1. Customer made phone call to call center.

  2. Call is delivered to agent.

  3. Agent created meeting in Vidyo platform.

  4. Agent sent meeting URL to customer (email, SMS, chat).

  5. Customer joined meeting at URL delivered from an agent.


Invite Expert (Simplified)

The scenario Invite Expert is between an agent and a call center expert that is using WDE. The starting point is wyhen a Vidyo session between the customer and agent is established.

  1. WDE agent sends request to establish IM session to WDE expert.

  2. WDE expert accepts session and application extracts meeting URL from interaction data.

  3. WDE expert sends request to join meeting as non-registered user.

  4. WDE expert joins the session and is now in conference with agent and customer.



After the WDE agent ends the Vidyo session, the WDE expert and customer will be disconnected from session.

Sequence Diagrams

Voice Escalation to Vidyo

Web Chat Escalation to Vidyo - Customer Initiates



Adapter API and Messaging

Signaling of the Vidyo session between the agent and customer differs based on use case. This section explains which messages are used to connect the agent and customer for Click to Vidyo and Chat to Vidyo (web chat).

Web Chat

No additional communication methods are required beyond the chat session established between the customer application and Workspace.  Whether using eServices or GWE, chat messages convey the requests and responses for a video conference.



Sent by customer application for a customer-initiated video conference.
Sent by Workspace for an agent-initiated video conference.


Sent by Workspace to indicate the agent has ended a video conference.

Message:<Guest Link>

Sent by Workspace to allow customer application to join a video conference.

Refer to the "Sequence Diagrams" section for additional details.


The Vidyo Server allows customer applications to open either a Web Socket or use a Rest API for communication to the Genesys framework. The successful Web Socket\Rest API connection triggers the Vidyo Server to initiate the creation of a Vidyo interaction using Orchestration Server (ORS) and Interaction Server (Ixn Server). The Vidyo Server attaches a Key Value Pair (KVP) acceptURL with the ORS session id to allow Workspace to respond with a guest link. The Vidyo interaction is placed into a Virtual Queue while waiting to be routed.

Routing configuration supports targeting a Workspace agent based on skills or membership in a specific agent group that supports Vidyo interactions. The Workspace receives the Vidyo interaction on its Vidyo openmedia channel in the same manner as a WorkItem, which is an EventInvite.  Upon accepting the Vidyo interaction, the Workspace uses the value of KVP acceptURL to post an HTTP message to ORS confirming acceptance.

Once the Workspace creates a video room, either automatically based on configuration or manually as selected by the agent, and receives a guest link from the VidyoWorks Platform, it then forwards the guest link. The Workspace does this by setting the value of KVP guestLinkURL to the guest link and posting another HTTP message to ORS.

The Vidyo Server now forwards the guest link over the Web Socket\Rest API connection to the customer application to allow the customer to join the video conference.

Refer to "Sequence Diagrams" section for additional details.

There is a 1:1 relationship between the Vidyo Server and ORS so that if there are multiple data centers, then there must be one Vidyo Server and one ORS in each data center.

The Vidyo Server accepts a Cancel request that it applies to the Vidyo Interaction. The Vidyo Server terminates the ORS session, and if the Vidyo Interaction:

  • Has not been accepted by an agent, the Vidyo Server submits a Stop Processing request to the Ixn Server.
  • Has been accepted by an agent, the Vidyo Server attaches KVP CancelVidyo=true for evaluation by Workspace. The Workspace reacts by presenting a notification to the agent. By default, this notification states the following: “The client has cancelled this request.”

A single function call from the customer application to the Vidyo Server handles the Web Socket\Rest API connection, triggers the Vidyo Interaction, and handles the callback with the guest link.

WebSocket API

Method clickToVidyo

_gv.api.clickToVidyo(data, onSuccess, , onFailure)


data: list of key value pairs formatted as a JSON string.

The UserData may optionally be included with the Click-to-Vidyo API call by providing a plain-text JSON-formatted object as argument data. This allows customer context to be included with the request. The Vidyo Server attaches the UserData as Key Value Pairs (KVP) within the UserData attribute of the newly created Vidyo interaction.


 onSuccess: A callback function that is called when the Guest Link is received.

Type: Function(Object guestLink)

onFailure: A callback function that is called when an error during a Guest Link request is encountered.

Type: Function(Object error)

An optional parameter may be included in the error response and is expected to be set by the ORS Strategy.  The parameter name must be UserDataGenesys and its value can be any plain-text JSON-formatted string. The Vidyo Server returns this data to the Customer UI.

For example, the ORS Strategy may contain a response:


The customer user interface would receive message content:


With the release of VidyoEngage for Genesys version, another function call from the customer application to the Vidyo Server requests to cancel the Vidyo interaction.

Method cancel


As mentioned previously, there are two possible outcomes:

  1. The Vidyo Server sends the Ixn Server a Stop Processing request.
  2. The Vidyo Server attaches KVP CancelRequest=true, which triggers the Workspace to present a notification to the agent.


The Vidyo Server holds webservices at URL https://<vidyohost>:<vidyoport>/VidyoServer/service/.

<vidyohost> - hostname where VidyoServer is running

<vidyoport> - http/https port where Vidyo server is listening

Method clickToVidyo

The service name is configurable at the Vidyo Server application object.


  • url: https://:/VidyoServer/service/click-to-vidyo
  • type: POST
  • contentType: "application/json; charset=utf-8"
  • data: list of key value pairs formatted as JSON String



The server responses are JSON Objects in the following formats:

  • Success - message contains ORS Session ID <orsSessionId> and Vidyo Server Session ID <id>, the <id> is then used in getURL method to get the Guest Link for the join meeting functionality
  • Error -
    • Vidyo server not running response is null
    • ORS Session not created contains error message and code from ORS


Method getURI(id)

The Method getURI is invoked after the Click to Vidyo POST is completed successfully. The input parameter is VidyoServer id assigned after ORS session is created and ORS session ID was successfully set. The “id” equals the browser session id. 


  • url: https://<vidyohost>:<vidyoport>/VidyoServer/service/<id>/guestLink
  • type: GET

The success message contains guest link that is then processed by client to join meeting room.



The server responses are JSON Objects in the following formats:

  • Success -
    • Flex link format, link with portal url and meeting key split into 2 parameters “url” and “key”
    • Join Link format, single join link provided in only one parameter “url”
  • Error -
    • General error (configuration, communication failure)
    • Routing Timeout at ORS (routing error)

General error occurs when Genesys backend components are configure incorrectly or not running. ORS routing timeout occurs when interaction is not delivered to an agent in specified timeout.

With response value <id> in parameter path, it is possible to map response to request sent from client.



Method Cancel

Canceling click to vidyo request is possible using cancel method. Cancel input parameter is vidyo server “id” of browser session. 


  • url: https://<vidyohost>:<vidyoport>/VidyoServer/<id>/stop
  • type: POST
  • contentType: "application/json; charset=utf-8"

The Success response message contains 2 possible formats based on VidyoWorks platform version. The Flex Link format is used by older version of Vidyo platform. Join link is used in new version. For detailed description of join link formats contact Vidyo support team.



The output message is a JSON object in the following format:

  • Success - success cancel contains all parameters with guestLink equals empty string
  • Error - has an error message and error code filled in. mapping error to vidyo session is possible by value <id> in path parameter



Web Integration Sample Widgets

The standalone widget deployment and integration is explained in separate document 4, Vidyo Adapter Sample Widgets. This document explains deployment and message flow of the sample widgets supplied with the release package. The sample widgets are supported from release 17.2.2. See installation package content folder “WebIntegrationSamples” package “WebIntegration_Vidyo_18.1.0.5_<release-date>.zip”.


Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.