Partners Blog Contact Us

Overview of VidyoEngage for Genesys


This article contains the following sections:



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.

Click to Vidyo

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


If Business Reporting is enabled, the Genesys Interaction Server must be available in the Voice Escalation to Vidyo use case.


Genesys Framework Components

The Genesys framework components included in the 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
  • Business Reporting
    • Interface to Genesys Interaction server
      • WDE is the client of the interaction server

The high level diagrams in this section show what interfaces needs to be configured to make the adapter work. For operating instructions, see the Using the Workspace article.

Business Reporting is optional and can be enabled by setting the workspace desktop application. The flow is applied only if reporting is enabled and is triggered by events coming from VidyoClient. For more information, see the Using the Workspace and Deploying VidyoEngage for Genesys articles.


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.


Transfer Video Session

The invite expert scenario occurs between the agent and that call center expert who is using WDE. The starting point is when a Vidyo session between the customer and agent 1 is established.


  1. WDE at agent 1 checks the list of target agents for Portal URI, IM, and Vidyo channel.

  2. WDE agent 1 sends the request to establish IM session to WDE agent 2.

  3. WDE agent 2 accepts the session, and the application extracts the meeting URL and room information from the interaction data.

  4. WDE agent 2 sends request to join the meeting.

  5. WDE agent 2 joins the session and is now in conference with agent 1 and the customer.

  6. Agent 1 leaves the session and WDE assigns agent 2 as the moderator.

  7. WDE at agent 2 side sets agent 2 as the moderator of the meeting.

  8. Agent 2 is in conference with the customer.

  9. Agent 2 leaves the session and does the meeting room cleanup and disconnects all the participants.

The transfer of the Vidyo meeting can be done only to the agent that has the same video meeting room configured as transfer initiating agent.


The sequence diagram below shows a two-step video session transfer:

  1. Step 1 is finished when the invited agent 2 accepts instant messaging and start Vidyo action is submitted from WDE plugin 2.

  2. Step 2 is finished after agent 2 joins the session and agent 1 clicks finish transfer or was disconnected automatically from the session.



Business Reporting

When reporting is enabled, WDE creates an outbound Vidyo session just for this purpose. The action create update and stop outbound Vidyo interaction is triggered by the VidyoClient.

Vidyo Session Established/Released Flow


  1. WDE agent sends request to create/join meeting. Meeting is created and VIDYO_CLIENT_OUT_EVENT_CONFERENCE_ACTIVE is delivered to WDE.

  2. WDE sends request to create outbound Vidyo interaction, and interaction server responds with positive acknowledgment.

  3. WDE agent sends request to stop meeting and VidyoWorks platform responds with VIDYO_CLIENT_OUT_EVENT_CONFERENCE_ENDED or VIDYO_CLIENT_OUT_EVENT_CONFERENCE_CLEARED.

  4. WDE sends request to update interaction data and request to stop processing.

Paticipant Event Flow

Starting point is an active Vidyo session with one or more participants and a new participant who is joining, sending events, and leaving.

Event 1 – Participants changed; new party joined

Event 2 – Mute/unmute, share/unshare

Event 3 – Participants changed; party left


  1. VidyoWorks delivers VIDYO_CLIENT_OUT_EVENT_PARTICIPANTS_CHANGED, and then WDE checks internal participants list and adds new record.

  2. Participant executed one of the reported actions (mute/unmute device, share/unshare content).

  3. Participant left the Vidyo session.

  4. WDE sends RequestChangeProperties to update the interaction user data with the participant information.


Sequence Diagrams

Sequence Diagram: Voice Escalation to Vidyo


Voice to Vidyo is the simplest way of connecting an agent and customer.

Agent and customer agree during a voice call that they want to escalate to a video conference. The agent creates the video session and distributes the guest link to the customer (via email or SMS). After customer joins the video session, the agent and customer can disconnect the voice call. The video session is operated from the WDE voice interaction window.

Sequence Diagram: Web Chat Escalation to Vidyo - Customer Initiates


In the Chat to Vidyo use case, the Genesys chat channel is used for sending Vidyo signaling messages. Here is a simple concept of the messages:

  • Message:VidyoRequest - Customer requested video call from the agent. The agent initiates the video session.
  • Message:<GuestLink> - Agent sends the guest link to the customer after the agent establishes the video session.
  • Message:VidyoRequestEnd (not in diagram) - The video session is ended after the agent leaves the call and stops the video session.

Sequence Diagram: Click to Vidyo


The sequence diagram shows the main application flows that may occur during the Vidyo Server daily operation:

  • Success flow ends with Notify Success GET at customer
  • Alternate error flow ORS routing timeout ends with Notify GET Error ORS Timeout at customer
  • Second alternate error flow GET Guestlink timeout ends with Notify Error GET at customer

All three views are shown in the following screenshots along with the messages.

Click to Vidyo - Success


When the agent accepts the interaction within the ORS routing timeout and creates a new Vidyo session within the GET Guestlink timeout, a successful Click to Vidyo session is established.

The result of this flow is that the customer and agent are connected to the meeting room. The agent connects from WDE and the customer connects from a browser.

Click to Vidyo - ORS Timeout


In the ORS Timeout scenario:

  • ORS sends request to URS with instructions about routing expression.
  • URS performs target selection, but no agent is available to accept the Vidyo interaction.
  • URS target selection timeout occurs.
  • Vidyo interaction is stopped and ORS responds to Vidyo Server with ORS routing timeout.
  • Vidyo Server notifies web page with error and web page notifies customer.


Click to Vidyo - GET Guest Link Timeout


In the GET GuestLink Error Timeout scenario: 

  • Genesys backend successfully selects agent and interaction is delivered.
  • WDE sends accept interaction notification to ORS.
  • Either agent manually or WDE automatically starts Vidyo session.
  • Vidyo backend is not able to serve Vidyo session.
  • HTTP GET Guest Link sent from web application reaches timeout.
  • Customer is notified about GET Guestlink timeout.

Sequence Diagram: Business Reporting

Create/Stop Vidyo Session


For interaction reporting, a CONFERENCE_ACTIVE event is delivered from the VidyoPlugin to WDE new Vidyo outbound interaction created at the Genesys backend. The outbound Vidyo interaction is stopped after the VidyoPlugin delivers a CONFERENCE_CLEARED event. This Genesys interaction is later used by the Genesys reporting engine for further Vidyo session reporting.

Join New Participant


The Join New Participant scenario reflects when a new party joins a Vidyo session. The party is captured with the Name and URI into the Vidyo outbound interaction user data. Together with other parties and actions performed during the call, it can be reported using the Genesys Historical reporting engines. WDE caches the information about the call parties until they leave the session. After the party is disconnected from the session, all data collected for this party are attached to the Genesys outbound Vidyo interaction user data. For more information about business reporting, refer to Vidyo Adapter Users Guide.

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.

Vidyo Server Click to Vidyo

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 the "Sequence Diagram: Click to Vidyo" section earlier in this article 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 starting with release 17.2.2. See installation package content folder “WebIntegrationSamples” package “WebIntegration_Vidyo_18.4.0.1_<release-date>.zip”.


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



Please sign in to leave a comment.