Setting Up Social Engagement

Overview

Social Engagement 8.5.2 introduced new data architecture. From 8.5.2 onwards, the API connectors to Twitter and Facebook are stored in the Genesys Hub. This allows the Genesys Engineering team to quickly adapt to changes to the APIs made by Twitter and Facebook, and thus protect customers from the volatility inherent in connecting to Social Networks via APIs. Now, besides installing Twitter and Facebook drivers on-premise, you must also set up and configure the cloud component, Genesys Hub.

Important

• Contact Twitter or Facebook to get your business ID before proceeding with account and channel creation in Genesys Hub.
• In release 9.0, Genesys Engage cloud for Social has been renamed to Genesys Hub. For information about the current active version of the Genesys Hub environment, see the Genesys Hub Release Note.

Legal Terms for Social Engagement 9.0.x

Important

If you have not already done so, please read and accept these terms to continue.

Installing On-premise Components

Important

Regardless of whether you are a new customer or an existing customer upgrading, it’s critical that you have already read and accepted the legal terms referenced above.

For New Social Engagement Customers:

1. Install Digital Messaging Server.
2. Install Social Engagement 8.5.x or 9.0.x

For Existing Social Engagement Customers:

1. Uninstall your existing drivers and remove their configuration options, as described here.
2. Proceed to install Social Engagement 8.5.x or 9.0.x, as described in the following section.

Installing Social Engagement 8.5.x or 9.0.x

1. Download the installation packages for Genesys Cloud API Driver for Twitter and Genesys Cloud API Driver for Facebook.
2. Locate the installation script for each driver (install.exe for windows and install.sh for Linux platforms) and run it.
3. While running the script you will be asked to enter/confirm:
   • Host Name
   • Configuration Server Host Name
   • Network port
   • Username
   • Password
4. Select a Digital Messaging Server object.
5. Answer any other questions and finish the installation.
6. If you are an existing customer,
   1. In Genesys Administrator Extension, select the Digital Messaging Server object, go to the Options tab, and select Import.
   2. Import the configuration files driver-for-facebook-options.cfg for Facebook and driver-for-twitter-options.cfg for Twitter (usually located in ...SMServer/media-channel-drivers/channel-facebook and .../SMServer/media-channel-drivers/channel-twitter). Select to NOT override the existing configuration options. At this point, you have two new configuration sections: [channel-facebook] and [channel-twitter]. For more information on importing .cfg files, see the Genesys Administrator Extension User Guide.
7. Use Genesys Administrator Extension to configure your Digital Messaging Server application for the Twitter and Facebook driver channels. For more information about the Digital Messaging Server options, see the Digital Messaging Server Guide.

Preparing for the Cloud Integration

After you have completed the above steps, you can gather the following information:

1. Identify and note the name of the company/organization that will be using the product—for example, XYZ Corp. This is your Account name for Genesys Hub.
2. For Twitter:
   1. Identify and note the handle, (and optionally, keyword strings) that you plan to use for your Twitter feed:
      • In most instances, using just the Twitter handle used for responding will be a sufficient first step; for example, ‘@XYZCorp_Help’.
      • It is CRITICAL that only the appropriate keywords are used. Twitter does not permit infinite access to the Twitter data feed. If very broad or popular keywords are used inappropriately, too much data will be consumed. If keywords such as: #JustinBieber, #iphone, #awesome were used the likely result would be a data failure.
      • Testing for keywords may be necessary in order to check and see if they are inappropriate. To do this go to https://twitter.com/search-home and enter the keyword(s) you plan to use (one at a time). View the search results and if they are relevant. Only relevant keywords should be used.
   2. Note the login and password credentials for any twitter handles you intend to use with Social Engagement.
3. For Facebook:
   1. Identify and note the names of the of the Facebook pages that you plan to use.
   2. Note the login and password credentials for the user that has administrator access to these Facebook pages.

Note also the following:

• Ports—Both Twitter and Facebook drivers (installed in Digital Messaging Server) connect to the Social Admin platform (in the Genesys Hub) using HTTPS on standard port 443. All API calls must go over HTTPS.
• Copy, Paste, Save—In the first seven steps of the following setup you will have to copy and save various pieces of text in order to use them in later steps. Please have a plain-text editor ready on your desktop and be prepared to save text (along with descriptions regarding the text) from steps 1 through 7.

Allowing host URLs for attachment support

When a brand's user sends an attachment through any Social Media platform or Messaging Apps, Genesys Hub temporarily stores these attachments in the Amazon S3 - Web Services. To download these attachments, customers are required to add some AWS URLS to their allowlist for security reasons.

Customers who need the AWS URLs for attachment support must allow the below URLs in their firewall:

*.s3.eu-west-1.amazonaws.com
*.s3-eu-west-1.amazonaws.com
*.s3.dualstack.eu-west-1.amazonaws.com
*.s3-control.eu-west-1.amazonaws.com
*.s3-control.dualstack.eu-west-1.amazonaws.com

In addition to the AWS URLs, customers must allow the following Twitter and Facebook URLs in their firewall to ensure that inbound attachments work properly.

Twitter

twitter.com
*.twitter.com
twimg.com
*.twimg.com
twttr.net
*.twttr.net
twttr.com
*.twttr.com
abs.twimg.com
*.abs.twimg.com

Facebook

*.facebook.com
*.facebook.net
*.fbcdn.net
*.fbsbx.com
*.akamaihd.net

Cloud Integration

Contents of this section:

1. Set up an account
2. Create a Twitter account channel
3. Create a Twitter service channel
4. Create a Facebook account channel
5. Create a Facebook service channel
6. Define an Admin user
7. Configure connections
8. Using more than one Twitter handle

1. Set up your company/organization account

The first step of deploying Social Engagement requires you to create an Account within Genesys Hub.

1. Navigate to https://socialanalytics.genesyscloud.com/gse/signup. You should see a form titled "Setup your Social Engagement Software."
   Important

   We recommend that you always use https://socialanalytics.genesyscloud.com to access Hub. But if you prefer a static URL, you can alternatively use https://static.socialanalytics.genesyscloud.com .

Setup Form
2. Populate the fields. Note and copy the value of Company/Org. Name to your text file (for example, Company/Org. Name: ##> ACME XYZ123 Corp.) You'll use this text in a later step of this setup.
   Important

   Email addresses such as Gmail and Yahoo Mail are considered as personal accounts. Therefore, you must use an email ID that reflects your organization’s domain when signing up for Hub. Existing users can update the email ID by accessing the My Profile page in Hub. If your Hub account is locked due to an invalid email address, contact Genesys Customer Care for activating your account again.
3. Click Continue.
4. Go to your email inbox and open the email titled "Confirmation required for Genesys Social Engagement deployment". If you don't see it, check your spam folder.
5. Follow the steps described in the email and select the option to log in using the email and password you've just created.
6. After successfully logging in, click My Account in the left navigation pane. The account update page is displayed.
7. Copy the value of the API key field to your clipboard using the Copy API key to clipboard option (displayed next to the field). You'll need it in a later stage of this setup.

API key
8. At this point, it is not necessary to make any changes to the other fields and attributes on this form.

2. Create a Twitter channel with the type Twitter:Account

The Twitter Channel with channel type 'Twitter:Account' is the mechanism you will use to authenticate to Twitter. Please be ready with your organization's Twitter handle (login) and Twitter password before proceeding.

Important

Your company or organization may use multiple Twitter handles. Step 8 below describes how to handle this situation.

1. Click My Channels in the left navigation menu. The Channels screen is displayed.
2. Click +Add Channel to create a new channel.

Channels

The New Channel window displays.


New Channel
3. From the Channel Type drop-down, select Twitter:Account.
4. Add a Channel Name. Please use the form <your channel's Twitter handle> - Twitter Account. Example: @Genesys - Twitter Account.
5. Optionally, add a description that indicates the planned usage of the channel.
6. Click Save and Proceed.
7. Click Login to Twitter.

8. Enter the Twitter credentials for your organization: username (handle) or email, and the password associated with your Twitter account. IMPORTANT: Also check Remember me.

9. A window that displays Access_token successfully saved indicates that you have successfully authenticated to Twitter.

3. Create a Twitter channel with the type Twitter:Service

A Twitter channel of type Twitter:Service will listen for mentions of your keyword(s) on Twitter.

1. Click My Channels in the left navigation menu. The Channels screen is displayed.
2. Click +Add Channel to create a new channel.
3. In the New Channel window (see the figure New Channel above):
   1. From the Channel Type drop-down, select Twitter:Service.
   2. Add a Channel Name. Please use the convention '<your channel's Twitter handle> - Twitter Service'. Example: @Genesys - Twitter Service.
   3. Optionally, add a Description.
   4. Click Save & proceed.
4. An extended form displays.

New Channel, extended
1. Click in Languages to select one or more languages.
2. Set up keywords and exclusions:
   • In Keywords, type the handle you will be using to listen for mentions, for example @Genesys, then hit Return or Tab. This will have the effect of sourcing all tweets based on the handle that you use.
     If there is a need, you may source additional posts by populating other words and phrases in the keyword field; for example, #Genesys. The inclusion of words or phrases in the keyword field is the only mechanism for sourcing posts from Twitter. If you have a need to use a broader range of words and phrases, it is important to review Best Practices for Managing Keywords in Twitter Service Channels below.
   • In Exclusions, type words or phrases for an additional filtration of Tweets. Tweets containing the excluded words or phrases do not enter the system even if the specified Twitter Handle(s) are mentioned in those Tweets. To allow Tweets in which the specified Twitter Handle(s) are mentioned, clear the Use the specified handles as keywords checkbox.
3. Click Yes in the Skip Retweets option if you want to skip processing Retweets. Skipping retweets means your system will not source tweets that have been retweeted, which may help cut out clutter and noise. You may want to select No if you want to analyze retweets and viral activity.
4. In Twitter Handle(s), just type the Twitter handle that you will be using to respond, example @Genesys. If you need to create multiple channels for the purpose of responding using different channels, see Using more than one Twitter handle to respond to customers.
5. Select the Use the specified handles as keywords checkbox to always apply the keyword exclusion mechanism (to filter the Tweets) even if the specified Twitter Handle(s) are mentioned in the sourced Tweets. Clear this option to allow Tweets in which the specified Twitter Handle(s) are mentioned and excluded keywords are present, to enter the system for processing.
6. Enter a value ranging from 0 to 3600 seconds in the RPC cache timeout field. See RPC cache timeout for detailed explanation on this setting.
7. In the Queue Message Type field, select the Twitter message types that you want to receive and process. You must enable at least one type of message between Private (Direct Messages) and Public (Tweets). Additionally, the Compliance Events option which is enabled by default, allows you to receive compliance events such as user delete events.
   Important

   • The Twitter compliance events processing is a mandatory requirement from Twitter. Although you can temporarily disable the Compliance Events option if you encounter any issues with the channel and you are debugging the system, it is recommended that you always keep the option enabled.
   • For more information on the configuration required for enabling Twitter compliance, see Enable compliance with Twitter.
8. To ensure the deletion of personal data (Personally Identifiable Information) from Twitter messages after the on-premise Twitter driver fetches the data, click Do not store personal data.
   Important

   This action is not retroactive. Pre-existing personal information remains in the UCS database.
9. Click Update and Proceed.

4. Create a Facebook channel with the type Facebook:Account

A Facebook channel of this type is the mechanism you will use to authenticate to Facebook. Please be ready with your organization's Facebook administrator login credentials for the relevant page(s) before proceeding. For simplicity, please make sure that you are currently logged into Facebook (with this administrator's password) using the same browser that you are using for this setup.

1. Click My Channels in the left navigation menu. The Channels screen is displayed.
2. Click +Add Channel to create a new channel.

Channels

The New Channel window displays.


New Channel
3. From the Channel Type drop-down, select Facebook:Account.
4. Add a Channel Name. Please use the convention <company name> - Facebook Account. Example: Genesys - Facebook Account.
5. Optionally, add a description that indicates the planned usage of the channel.
6. Click Save and Proceed.
7. An extended form displays.

Update Channel
8. Click Login to Facebook. A pop-up appears asking you to log in to Facebook

Facebook Login
9. Log in with the admin credentials for the Facebook pages that you want to use. It is important that these user credentials have Facebook admin access to all of the Facebook pages to be used.
10. Provide permissions to the pages you would like to manage for the business integration to work. Select the pages you want to use from Genesys Social Engagement.
    
11. For a failproof integration, grant access to all permissions; otherwise, Facebook integration may not function properly. If you are in doubt, consult with Genesys customer care.
    

    After setting up the permissions a confirmation message is displayed.

    
12. Once you have logged in and authenticated you should see a message access_token successfully saved, close window. You may close this window.

Important

• If the credentials for the Facebook administrator are changed at any time after configuring the account channel, then login again with the new credentials and click Update.
• You can modify the integration permissions any time after linking the Genesys Social Analytics application to your Facebook account. You can modify these settings on the Business Integrations page within your account.

  

For more information on business integrations and permissions, see:

How do I edit the privacy and settings for my business integrations or remove them from Facebook?

Permissions, Features, and Tasks

5. Create a Facebook channel with the type Facebook:Service

A Facebook channel of this type is used to listen for posts, comments, and messages on Facebook.

1. Click My Channels in the left navigation menu. The Channels screen is displayed.
2. Click +Add Channel to create a new channel.

Channels

The New Channel window displays.


New Channel
3. From the Channel Type drop-down, select Facebook:Service.
4. Add a Channel Name. Please use the convention <company name> - Facebook Service. Example: Genesys - Facebook Service.
5. Optionally, add a description that indicates the planned usage of the channel.
6. Click Save and Proceed.
7. Update Channel displays.

Update Channel
8. Make a note of the Channel ID—it will be needed for a later step
9. Click Facebook Pages to get a drop-down list of all of the Facebook pages that the Facebook user is an administrator of. Select each page that you want to monitor.
10. Enter a value ranging from 0 to 3600 seconds in the RPC cache timeout field. See RPC cache timeout for detailed explanation on this setting.
11. In the Queue Message Type field, select the Facebook message types that you want to receive and process. You can see that both the Private and Public messages options are enabled by default. Disable the option that does not suit your requirement. Enable the Ads Interactions option to receive ad referral events. See Sending a message to verify an interaction for detailed explanation on how to create an ad so the user could send a message and initiate the interaction. Additionally, you can also opt to receive private or public message by configuring the **option name**
    Important

    You must switch your Facebook account to Production mode in your Facebook Account channel. See Production Toggle for more explanation on this setting.
12. To ensure the deletion of personal data (Personally Identifiable Information) from Facebook posts after the on-premise Facebook driver fetches the data, click Do not store personal data.

    This action is not retroactive. Pre-existing personal information remains in the UCS database.

13. Click Update.

6. Define an Admin user for the account

You will also have to create a new admin user login and password in order to facilitate communication with Digital Messaging Server.

1. Click Users in the left navigation menu. The Users screen is displayed.

Users
2. Click +Add User. The New User screen is displayed.
   

   New User
3. In the First Name field, type the company's name followed by a 1; for example, Genesys1.
4. In the Last Name field, type admin.
5. In the Email field, type an email address using a format like the following: Genesys1_Admin@GenSocialEngage.com. Copy and paste this email address to your notepad file as it will be used for a later step of the deployment.
   Important

   This email address will not be used for sending or receiving emails. It is only used to manage logging in, and communications between the cloud and on-premise components of Genesys Social Engagement.
6. Make sure that Admin is selected in the Roles field.
7. Click Create.
8. Now return to Users. You should see a list of the users associated with the account that you have set up.
9. Click Reset Password for the admin user that you have just created.
10. Enter a new password, and make a note of it (copy and paste to your text file); also make a note of associated email address. You will use them in a later step of the deployment.

7. Configure connections

To configure connections between the on-premise Digital Messaging Server and the cloud-based Account and Channels that you set up in Steps 1 through 5 above, you must set values for certain configuration options.

1. Import the configuration options files, being sure to select No in response to Do you want to overwrite the existing data?
2. Set option values both the Twitter and Facebook Drivers. The values are based on the setup in Steps 1–6. Be sure that your text file has all of the text that you've copied and pasted clearly identified. Set the option values by copying and pasting the exact values from your text file (complete descriptions of these options are on this page).

   Option Values

   Option	Value
   gsa-account-name	Company/Organization name from Step 1
   gsa-api-key	API key from Step 1
   gsa-channel-id	Facebook—Facebook:Service Channel ID from Step 5
   	Twitter—Twitter:Service Channel ID from Step 3
   gsa-channel-name	Facebook—Facebook:Service channel name in Step 5
   	Twitter—The exact text used in the Twitter:Service channel name from Step 3
   gsa-url-base	socialanalytics.genesyscloud.com/api/v2.0
   gsa-user-name	The admin email address from Step 6
   password	The admin password from Step 6

Sample values are shown in the following figures (click to enlarge). Note that the values of gsa-api-key, gsa-channel-id, and password are masked in these figures for privacy.



Facebook Sample

Twitter Sample


3. Test both channels by submitting posts via Twitter and Facebook, and seeing if they appear in the customer’s Workspace.

8. Using more than one Twitter handle to respond to customers

Administrators can configure multiple Twitter handles using a single Twitter Service channel in Genesys Hub. This feature allows agents to select a Twitter handle from which the reply message is sent to the brand’s user.
Follow these steps to configure multiple Twitter handles:

1. Add a Twitter Account channel for each Twitter handle that you wish to add.
2. Access the Update Channel page of the Twitter Service channel.
3. Enter the Twitter handle names in the Twitter Handle(s) field.

Muliple Twitter handles
4. Enter the default handle in the Default reply handle field.
5. Click Update to save the settings.

Upgrading drivers

Depending on your environment, follow these steps to upgrade Genesys Cloud API Driver for Twitter and Genesys Cloud API Driver for Facebook.

For Windows

1. Stop backup DMS using GAX or SCI.
2. Navigate to Control Panel and locate Genesys Cloud API driver for Twitter or Genesys Cloud API driver for Facebook. Uninstall it.
3. Find setup.exe file in the newer installation package and run it.
4. Select DMS which has been stopped and install the driver(s).
5. Start backup DMS.
6. Switch over and repeat Step 1 to Step 4 for primary DMS.

For Linux

1. Stop backup DMS using GAX or SCI.
2. Navigate to media-channel-drivers directory in the DMS install location.
3. Delete the older install dirs channel-twitter or channel-facebook.
4. Find the install.sh file in the newer installation package and run it.
5. Select DMS which has been stopped and install the driver(s).
6. Start backup DMS.
7. Switch over and repeat Step 1 to Step 5 for primary DMS.

Production Toggle

You can toggle between production and non-production (lab, staging, test) modes using a switch in Hub.

1. Log in to Hub.
2. Click Channels in the left-hand menu to get a list of the channels you have access to.
3. Select a channel and click Edit.
4. Slide the toggle to the right to engage Production mode.
   

Note the following:

• Internal Service Level Agreements (SLAs) apply only to accounts in production mode.
• Genesys carries out recovery, or assists with it, for Production accounts only.
• Production mode is indicated in reports.
• Production mode requires all required licenses to be in place.
• Switching to Production mode creates a distribution list to send emails and updates in the Hub Status page.
  

RPC cache timeout

The RPC cache timeout, in seconds, is used for caching messages that agents might send repeatedly over a period. The purpose of this timeout is to prevent accidental loops in workflow or automated agents (chatbots) from sending duplicate messages too often (quicker than the specified timeout).

For example, if you enter 3600 (3600 seconds or one hour) in this field and the driver sends the same message repeatedly, Hub will not forward the message from the agent more than once in a duration of 3600 seconds (one hour). Additionally, each new attempt to send a duplicate message resets the timeout.

The default value is 90. The value 0 disables the timeout.

Tip

If you are planning to use chatbots, Genesys recommends that you set a smaller value or disable the timeout by setting the value to 0. Chatbots are expected to send duplicate messages.

Best Practices for Managing Keywords in Twitter Service Channels

When setting up a Twitter:Service channel, you have the option to add any text in the Keyword field. It is important to use only appropriate keywords. If your keywords are very common or popular, your inbound feed may be cluttered with too many useless posts. In extreme scenarios, Twitter may cut off access to data if the data volumes are too high. This might occur for example if you were to input keywords such #awesome or hello.

Warning

If a channel's inbound traffic exceeds 300 tweets per minute for a certain keyword, the keyword is removed from the channel automatically. The keyword can be added back by the admin account after 3 days, when the keyword gets unblocked. However, users can request the Genesys representative to add the keyword back before the 3 days block period expires. Users can run recovery on the missing data after the keyword has been added back and there is no risk of the keyword getting blocked while data recovery is running as the recovery uses a different API.

If one were to set up a channel to monitor mentions of Genesys on Twitter, some appropriate keywords and phrases would include: @Genesys, #Genesys, and Genesys software.

It is essential to check that keywords you use are not too broad or ambiguous. Go to https://twitter.com/search-home and check the keyword(s) you plan to use (one at a time). You will need to view the search results and assess the results. If there were a company called "United Ultra Local Bank Inc." one might be inclined to use the keyword #United. This would be a mistake, as it would source a flood of unnecessary posts from Twitter users that are submitting posts relating to #United Nations, #United States, Manchester #United, and so on. Even worse would be #Check, savings account, #balance, or overdraft as these are even more generic.

Languages filter

You can configure the supported languages for Twitter interactions using the Allow any language option or Languages field in the Update Channel page in Genesys Hub. Tweets in the supported languages only are downloaded and displayed to agents. Even if a Tweet matches your keyword, the Tweet is not downloaded if the language is not supported as per the channel configuration.

You can select the Allow any language option to allow Tweets in all languages or you can specify supported languages in the Languages field. Selecting Allow any language hides the Languages field.

Sending a message to verify an interaction

You can create and use ads that click to Messenger to begin a conversation. You can also customize your conversations in Messenger to meet your business specific needs.

1. Refer to https://developers.facebook.com/docs/messenger-platform/discovery/ctm-ads#createad to create an ad. You can create using an image, video, or carousel ad post, and also setup a greeting message, quick replies, and so on.

Important

Facebook may update the UI eventually and you end up creating a new ad. It is recommended to use one of your tracked Facebook pages you have configured in the service channel during this ad setup.

1. Once you create your ad, install the Facebook Messenger mobile application. Remember to login with the same account that you are using in the Ads manager.
2. Go to the Ad Preview window and click Share → Preview on device → Preview Message. An Ad account block warning displays asking you to publish the ad first to view the Preview message menu. This triggers the review process, which may end up with rejection. Note that your ad account will be blocked on repeated rejections.

• You will receive an ad preview to your device and on interacting with the ad, a referral event is received into the channel.

Frequently asked questions

Can I use proxy between Genesys Hub and DMS?

You can configure DMS to use HTTP proxy. See Other DMS Configuration for information on enabling proxy server.

Do Genesys Hub and DMS use a load balancer between them?

DMS, Genesys Hub, and Social Engagement drivers require a single host to connect to.

Can a third-party security solution such as Trend Micro be used to scan interactions for threats before reaching on-premise components?

Assuming that Trend Micro security divides traffic into several routes, the suggested setup is:

[DMS] > [reverse proxy] > [Trend Micro pool] > [Genesys HUB]

Which part of the Social Engagement traffic ends in Genesys Hub?

All Social Engagement traffic ends in Genesys Hub. There is no pass-through traffic, as Hub does some additional processing before passing it further to DMS.

Does Genesys Hub perform any type of traffic scanning?

No. Hub does not scan the traffic.

Does Genesys Hub take any action if a malicious file is found?

Hub does not scan the attachments that are sent or received from social media.

How are interactions with attachments handled?

• Facebook attachments are sent as URLs. The Facebook driver fetches this data directly from Facebook.
• Twitter DM attachments are stored as links, but they are fetched from Hub as Twitter requires OAuth 1.0 authorization for these media links.

DMS uses these links to download the attachments and save them in UCS where they are available for WDE for further handling.

Can Genesys Hub be integrated with third-party software such as Splunk and Trend Micro?

No. Genesys Hub does not integrate with these third-party applications. However, it is possible to configure them in an on-premise environment.

What is the type of authentication used between drivers and Genesys Hub?

A token-based authentication is used. The drivers send the username, password, and account token to acquire a unique authentication token valid for 24 hours. This authentication token is used to authenticate requests to Hub.

Does Genesys Hub store any data?

All data received from social media platforms is stored in Genesys HUB for a limited time. The data retention period is 28 days.