Deploying WhatsApp

Prerequisites

Component	Prerequisites
Digital Messaging Server (DMS)	For basic functionality, 9.1.003.12 or later is required. For rich media notifications support and parallel processing of ESP requests, 9.1.005.04 or later is required. For DMS scalability, DMS 9.1.007.05 or later is required.
Workspace Desktop Edition (WDE)	Minimum version 8.5.127.06 or later is required
eServices Manager	For basic functionality, 9.0.000.09 or later is required. For rich media notifications support, 9.0.002.05 or later is required.
Genesys Driver for use with Genesys Hub	For DMS scalability, Genesys Driver for use with Genesys Hub 9.1.007.06 or later is required.

Deploy Digital Messaging Server

Follow the installation procedure for Digital Messaging Server.

Create a WhatsApp channel in Genesys Hub

Follow the procedure for creating a WhatsApp channel in Genesys Hub.

Install the channel driver

1. Navigate to the folder that contains the installation package for Genesys Driver for use with Genesys Hub.
2. Run the installation for Genesys Driver for use with Genesys Hub:

   On Windows, run setup.exe

   On Linux, run install.sh

3. When prompted by the installation dialog, specify the proper Configuration Server parameters for your environment and select the desired Digital Messaging Server application.
4. After installation, locate the GenesysHubDriver.cfg configuration file in the \<Digital Messaging Server application>\media-channel-drivers\channel-ghub\Configuration folder.
5. In GAX, open your Digital Messaging Server Application, go to the Options tab, and import options from the GenesysHubDriver.cfg file.

Configuration

All options are documented in the Options Reference.

Configuring Chat Server

Set the following Chat Server options:

• transcript-auto-save = 1

  This setting automatically saves the chat transcript in UCS in case of a solution failure.

• xml-request-max-size = 100000

  Setting this value to 100 KB or more is required when using rich messaging functionality.

Follow Deployment guidelines for async and regular chat in the Chat Server Administration guide.

Endpoints

• Chat Server: in the [endpoints] section, add a queue called async-chat-greet-queue.
• Digital Messaging Server: in the [channel-*any name*] section for your WhatsApp channel, add an endpoint called session-chat.

(You must use a comma before the tenant ID. For example: ,1:session-chat.)

Deploy Genesys Hub Plug-in for Workspace Desktop Edition

1. Install Workspace using the ClickOnce deployment procedure.
2. Configure and install the plugin, ensuring that your configuration procedure includes importing the template and metadata for the plugin. This makes roles and other required items available.
3. Open the Workspace Desktop Edition Deployment Manager.
4. Create a deployment package. In the Customization section, ensure that you select Genesys Hub Plug-in for Workspace Desktop Edition.

   

5. Deploy the package on a web server.

   

6. If you are using role-based access control,
   • You must assign all Workitem privileges. The plugin does not support unassigned Workitem privileges.
   • Assign InteractionWorkspace.WhatsApp.canUse privileges. This allows agents to load the WhatsApp plugin. If this permission is not set, the plugin will not load.
7. Provide values for the configuration options that you added to your Workspace Application, as described in the next section.

Configuring the Plugin

Plugin Options

All options for the plugin are located in the [interaction-workspace] section. Options are documented in the Options Reference.

When using the sample business process, set the following configuration options in the [interaction-workspace] section:

• whatsappsession.on-hold-queue to async-chat-return-queue
• workbin.whatsappsession.in-progress to async-chat-main-workbin

Workspace Desktop Edition Options

Workspace Desktop Edition options are documented in the Configuration Options Reference section of the Workspace Desktop Edition Deployment Guide. The following settings are recommended:

• contact.directory-displayed-columns = LastName,FirstName,PhoneNumber,EmailAddress,_msg_ProfileNickname
• contact.directory-search-attributes = LastName,FirstName,PhoneNumber,EmailAddress,_msg_ProfileNickname
• contact.displayed-attributes = Title,FirstName,LastName,PhoneNumber,EmailAddress,_msg_ProfileNickname
• display-format.case-name-format = $Contact._msg_ProfileNickname$|$Contact.FirstName$ $Contact.LastName$|$Interaction.MainParty$
• display-format.customer-name-format = $Contact._msg_ProfileNickname$|$Contact.FirstName$ $Contact.LastName$|$Party.DisplayName$
• interaction.window-title = ($Contact.FirstName$ $Contact.LastName$ $Interaction._msg_ProfileNickname$|$Interaction.MainParty$) - $Interaction.Type$ - $Window.Title$
• toast.window-title = ($Contact._msg_ProfileNickname$|$Contact.FirstName$ $Contact.LastName$|$Interaction.MainParty$) - $Window.Title$

Important

The plugin supports only the Default and HighContrast themes. If any other theme is specified, the plugin icons will be missing.

Other configuration

• Create the following media type in the Configuration Server database: whatsappsession. Next, add the whatsappsession media type to your environment's capacity rules and specify how many instances of whatsappsession interactions are allowed simultaneously.

• Create a Business Attribute of type Interaction Subtype with the name InternalConferenceInvite.

• Genesys recommends that you increase the default value of the session-shutdown-timeout option in DMS to 1800 (30 minutes).

Contact Attributes

In Genesys Administrator or Configuration Manager, create the following Business Attribute Values for the Contact Attributes Business Attribute:

Profile Nickname

• Name—_msg_ProfileNickname
• Display Name—Profile Nickname

In the Annex tab, add the following options in the [settings] section:

• is-searchable = false
• is-sortable = false

Automatic notifications configuration

The following options are used to configure the automatic notifications feature for WhatsApp:

• whatsappsession.enable-free-msg-timespan-monitoring—Enable or disable the feature by setting this option to True or False.
• whatsappsession.free-msg-timespan—Set the timeout after which agents can only send Notifications.
• whatsappsession.default-notification-text—Provide the default notification text that will be sent to the brand's user when an agent sends a message after the configured timeout.
• whatsappsession.default-notification-id—Provide the notification ID for the default notification text.
• whatsappsession.default-notification-language—Indicate the language used in the default notification text.

Important

Values of options, whatsappsession.default-notification-text, whatsappsession.default-notification-id, and whatsappsession.default-notification-language must match with the values in the WhatsApp template for the default notification. For more information, refer to Create message templates for your WhatsApp Business API account.

Location preview configuration

The following options are used to configure the map provider for incoming locations:

• whatsappsession.location-map.browse.query—Provide the URL for navigating to the map provider website.
• whatsappsession.location-map.preview.query—Request the configured map provider to respond with a location preview.
• whatsappsession.location-map.preview.height—Set the height of the location preview, in pixels.
• whatsappsession.location-map.preview.width—Set the width of the location preview, in pixels.

The location preview image is rendered by the third-party map provider if the option whatsappsession.location-map.preview.query is not empty. The Genesys Hub Plug-in for Workspace Desktop Edition makes a REST API call and draws the image from response. This is called as static map. One of the following map providers can be used:

• Bing Maps
• Google Maps
• Yandex Maps
• Any map provider with the similar REST API and image response

Usually, the common input data for all map providers is as follows:

• Access token
• Scale
• Image width and height
• Position latitude and longitude

All this data except the position (latitude and longitude) must be hard coded into the query string template. For latitude and longitude, you must have the placeholders {LATITUDE} and {LONGITUDE}. These two values are dynamically updated with values from the inbound location message JSON.

For height and width of the location preview, the placeholders are {HEIGHT} and {WIDTH}.

Role permissions

Sending attachments

Administrators can control whether an agent is allowed to send attachments in WhatsApp interactions using the following permissions:

Permission name	Display name	Description
InteractionWorkspace.WhatsApp.canSendFiles	WhatsApp - Can Send Files	The agent is permitted to send files as attachments
InteractionWorkspace.WhatsApp.canChangeAttachmentsInNotification	WhatsApp - Can Change Attachments in Notification	The agent is permitted to change attachments in Notifications
InteractionWorkspace.WhatsApp.canChangeAttachmentsInReplyButton	WhatsApp - Can Change Attachments in Reply Button	The agent is permitted to change Attachments in Reply Button

Configuration for sending outbound messages from other channels

Role permissions

Permission name	Display name	Description
InteractionWorkspace.WhatsApp.canCreateNewSessionFromOtherMedia	WhatsApp - Can Create new session from other media	The agent can create a new outbound WhatsApp session from other media channels

Configuration Option

Administrators must add or configure the following option if the key-value pairs _umsOutboundSessionConfig is missing from the attached data of the Business Process:

Option Name: whatsappsession.outbound-session-config
Default Value: No default value
Valid Values: Valid JSON object string
Changes Take Effect: Immediately

Description: JSON object string containing a list of channels to be used for outbound sessions in other media interactions.

Sample Value: {"channels" : [{"server-name": " DigitalMessagingServer ","channel-name": "channel-whatsapp-1","business-id": "19251112221"},{"server-name": " DigitalMessagingServer ","channel-name": "channel-whatsapp-2","business-id": "19251112222"}]}

Configuration for displaying emojis in chat transcript

This method helps you to configure the plugin to display emojis in chat transcript for both inbound and outbound messages.

1. Identify the emoji that you need to add. For example, 🥰 (smiling face with hearts) is used in this procedure.
2. Find the corresponding Unicode number for the emoji. In our example, it is 1f970.
3. Prepare a PNG file with the emoji and save it in the name format, <Emoji Unicode>.png. In our example, the file name is 1f970.png.
4. Navigate to the installation folder of the Genesys Hub Plugin which is <WDE installation folder>\GenesysHub. Find the CustomEmojis.xml and open it in a text editor.
5. In the CustomEmojis.xml, add an emoji definition in the format, <Emoticon Emoji="🥰" Code="1f970"/>. You can refer to any third-party site, for example, Copy and paste emoji to copy and paste the emoji easily.
6. Copy and paste the PNG file from Step 3 into <WDE installation folder>\GenesysHub\Images\Emojis folder.

Uninstalling or upgrading

Driver

Uninstalling the driver

1. Stop the DMS application with the driver. This can be done for example via GAX (or Services if using Windows).
2. Uninstall the driver:
   • On Windows through Control Panel > Programs and Features.
   • On Linux by running the ./uninstall_custom.sh script from the media-channel-drivers/channel-ghub/uninstall folder.
3. Verify that the folder channel-ghub was removed under folder media-channel-drivers.

Upgrading the driver

1. Follow the procedure above to uninstall the old version of the driver.
2. Install the new version of the driver, using the instructions above on this page.
3. Start the DMS application with the driver.

Plugin

Uninstalling the plugin

1. Uninstall the plugin.
2. Create a deployment package with Workspace Desktop Edition Deployment Manager.
3. Deploy the package onto a web server.

Upgrading the plugin

1. Follow the procedure above to uninstall the old version of the plugin.
2. Install the new version of the plugin, using the instructions above on this page.
3. Create a deployment package with Workspace Desktop Edition Deployment Manager. Ensure you select the plugin in the Customization section.
4. Deploy the package and plugin onto a web server.