You are here: Advanced > Web Gateway

Web Gateway

The Web Gateway makes it easy for customers to deploy web chat by copying and pasting a short snippet of

HTML, the Widget Snippet from the Web Gateway Admin site, to the customer’s existing website. With this snippet, the Web Gateway chat widget will now appear on the customer website, allowing visitors to click the widget and start a web chat.

System Requirements

Clarity Connect

Clarity Web Gateway requires an instance of Clarity Connect version 4.0 or higher.

Skype for Business Infrastructure

Clarity Web Gateway uses Microsoft's Unified Communications Web API (UCWA) and therefore requires a Skype for Business enabled environment. In an on-premise configuration, the partner must provide a workable Skype for business environment and infrastructure in a Microsoft-supported deployment configuration.

Network Infrastructure

Below is a table of the preferred and required ping times between various components of the Clarity Web Gateway.

Server A Server B Rec. Ping Max. Ping
Application Server Database 10 ms 50 ms
Application Server Clarity Connect Integration Service 50 ms 150 ms
Application Server Skype for Business Front-End 50 ms 150 ms

Websockets Support

The Web Gateway supports and uses WebSockets if you provide a path in your network infrastructure to the Web Gateway Application Server(s) that allows WebSocket connections. If no such path exists, the Web Gateway will gracefully degrade to using long polling instead. If there are still problems, WebSockets can be entirely disabled through the “Supported SingalR Transports” setting in the Web Gateway Admin Site. See the Administrative Site Guide for more details.

Application Server

Clarity Web Gateway should be deployed to its own server. Please note that if other resource-intensive applications are running on the same application server, the specifications below may need to be adjusted upward. Virtualization is supported.

Option 1: Physical Application Server

Operating System:

Windows Server 2012 (64-bit only), Windows Server 2012 R2 (64-bit only), Windows Server 2016 (64-bit only)

CPU:

64-bit processor, quad-core, 2.0 GHz or higher
(Note: Intel Itanium processors are not supported for Skype for Business Server server roles)

Memory:

16 GB

Disk:

Local storage with at least 100 GB free disk space on a fault tolerant drive array consisting of drives

operating at a minimum of 10.000 RPM. Solid state drives may also be used.

Network:

1 network adapter required (more supported), 1 Gbps or higher

Option 2: Virtual Application Server

Operating System:

Windows Server 2012 (64-bit only), Windows Server 2012 R2 (64-bit only), Windows Server 2016 (64-bit only)

CPU:

Four virtual CPU cores.

Memory:

16 GB

Disk:

Local storage with at least 100 GB free dish space on a fault tolerant drive array consisting of drives operating at a minimum of 10,000 RPM. Solid state drives may also be used.

Network:

1 network adapter required (more supported), 1 Gbps or higher. For Hyper-V, use the standard VM network adapter, not the legacy network adapter.

Database

Clarity Web Gateway requires Microsoft SQL Server 2012. Clarity Web Gateway will create a runtime database.

Locating Clarity Web Gateway databases on the same server as the Skype for Business Server databases is not supported for performance reasons.

Anti-Virus Exceptions

Clarity Web Gateway requires that log files (files ending in .log) contained in the paths for the application install be excluded from any Anti-Virus scans. Scans can delay or lock files causing issues.

Installation

Installation Overview

The Clarity Web Gateway installation process is broken up into pre-implementation and install processes. This separation ensures that all necessary components are in place before the installer is run.

Pre-Implementation

Before beginning the pre-implementation, review and fill out the Configuration Worksheet according to the directions in that document. The Configuration Worksheet contains all necessary details of the Clarity Web Gateway configuration, and can later be used as a reference document for troubleshooting or upgrades.

The pre-implementation process is broken down into tasks and divided into three groups. Each group of tasks requires a different set of permissions. These tasks must be completed in the order presented. An overview of all tasks is below.

Any parameters from the Configuration Worksheet used for tasks in this document are shown in bold purple in the following format: {Parameter Name}. To execute the task, replace the {Parameter Name} with the value of that parameter from the Configuration Worksheet.

When it is necessary to run command line tasks, the command is shown in blue. As with other tasks, replace any Configuration Parameters with values from the Configuration Worksheet are shown in bold purple.

For example: $x = New-CsWebOrigin - Url "https://{API and Content Site Hostname}"
Becomes: $x = New-CsWebOrigin - Url "https://webgateway-api.mycompany.com"

Where possible example values and output are shown.

Tasks by Role

  • Domain Administrator
    • Install SSL Certificate
    • Create DNS Entries
    • Create Service Account
    • Create Low Permission Account
  • Skype for Business Administrator
    • Install Skype for Business Server Cumulative Updates
    • Enable UCWA
    • Add API URL to UCWA Whitelist
    • Setup the Clarity Web Gateway Application Server
  • SQL Administrator
    • Create the Web Gateway database
    • Grant database permissions to the Service Account
  • Clarity Web Gateway Installer
    • Ensure that all tasks in this list are complete
    • Ensure that the Configuration Worksheet is completely filled out

Domain Administrator

Install SSL Certificate

Each Application Server will requires one or more SSL certificates to enable HTTPS for the API and Admin sites.

The SSL certificate for the API and Content Site must be valid for the DNS same of the API site. The DNS Name for the API and Content Site is the {API and Content Site Hostname}, so something like “webgateway-api.mycompany.com”. You will have to grab these certificates thumbprint to use as the

{API and Content Site SSL Certificate Thumbprint}.

As the Web Gateway API and Content Site will be publicly accessible you will need the certificate to be from a well-known certificate authority such as Entrust rather than a self-issued certificate.

The SSL certificate for the API and Content Site must be valid for the DNS name of the Admin Site. The DNS Name for the Admin Site is the {Admin Site Hostname}, so something litre “webgateway-admin.mycompany.com”. You will have to grab these certificates' thumbprints to use as the {Admin Site SSL Certificate Thumbprint}.

If the API and Admin sites are on the same domain, you can use just one certificate by using a wildcard certificate for the domain or a regular certificate that was issued with Subject Alternate Names that include entries for both the API and Admin Sites. For example, “DNS-webgateway-apr.claritycon.com” and “DNS-webgateway-admin.claritycon.com”

IMPORTANT: You are responsible for maintaining and updating expiring certificates. You may want to set up a calendar reminder for when they are going to expire soon.

Create DNS Entries

Create DNS Entries (A Records) for the DNS Names of the API and Admin Site, the {API and Content Site Hostname} and the {Admin Site Hostname} respectively that point to the Application Server or to a Load Balancer for load-balanced deployments.

Create the Service Account

You can use any name you want; our default recommendation is a user called webgatewaysvc, such as “mycompanydomain\webgatewaysvc”. We strongly recommend giving this account a non-expiring password due to the number of services that will use this proxy account (all application servers, IIS application pool, etc.). If you choose to give it an expiring password, you will be responsible for changing the password and updating references when necessary.

→If you haven’t already, record the Service Account name and password as {Service User} and {Service User Password} on the Configuration Worksheet.

NOTE: The installer will set permissions for the Service Account while installing Clarity Web Gateway on each application server.

Create the Low Permission Account

Create a domain account “mycompanydomain\webgatewaylowperm” in the Domain Users group. Give this account a non-expiring password. This account will be used by IIS to allow for public, anonymous access to the images, CSS, HTML, and JavaScript for the Web Gateway chat widget and chat client.

Grant this user Read access to the Content shared directory.

→ If you haven’t already, record the Low Permission Account name and password as

{Low Permission User} and {Low Permission User Password} on the Configuration Worksheet.

Skype for Business Administrator

Enable UCWA

In order to enable UCWA you must run the Bootstrapper (located at “%Program Files%\Skype for Business Server 2015\Deployment\Bootstrapper.exe”) on every director, standard edition, and enterprise edition front end server in your topology. After this, please enter the appropriate URL as the {Lync Autodiscover Address} parameter on the Configuration Worksheet. The address will be “lyncdiscover”.<lyncdomain>. An example of this would be “https://lyncdiscover.mycompany.com”.

Add API URL to UCWA Whitelist

A URL to the API need to be added to the UCWA allowed cross-domain URL whitelist so that it will be able to successfully authenticate with UCWA without running into cross-site scripting problems.

This URL can be constructed by pre-pending "https://" to the {API and Content Site Hostname}.

This needs to be done or every Front End, Edge, and Director Server in your Skype for Business topology. To do this execute these commands in Skype Server Management Shell.

  1. $x = New-CsWebOrigin -Url "https://{API and Content Site Hostname}"
    This command will not return any output. Ex.
    $x —— New-CsXebOrigin -Url "https.//webgotewoy-opi.mycompony.com"
  2. Set-CsWebServiceConfiguration -Identity global -CrossDomainAuthorizationList @{add=$x}
    This command will also not return any output. Ex:
    Set-CsWebServiceConfiguration -Identity global -CrossDomoinAuthorizotionList @{add=$x}
  3. To check and mate sure the proper URL was added to the whitelist, execute the following command and validate that the API URL is listed in the results
    Get-CsWebServiceConfiguration | select —ExpandProperty CrossDomainAuthorizationList
    Ex.
    Get-CsWebSewiceConfiguration | select —ExpandProperty CrossDomoinAuthorizationListOutput:
    Url : https://testsite.mycompany.com
    Url : https:/, webgateway-admin.mycompony.com

Set Up the Clarity Web Gateway Application Server

These steps apply to each Application Server, unless otherwise specified.

Install Windows Roles and Features

This step must be performed on each Application Server by a user with local administrator (or higher) permissions on the application server.

Open Windows PowerShell as an administrator. This can be done by going to the Start menu, typing powershell, right-clicking Windows PowerShell in the list, and clicking Run as administrator.

When the PowerShell console opens, type: Import-Module ServerManager and press Enter.

Then enter the following command and press Enter.

This will install all of the required Windows roles and features, and then automatically restart the server.

Add-WindowsFeature -Name Web-Default-Doc, Web-Dir-Browsing, Web-Http-Errors, Web-Static-Content, Web-Http-Logging, Web-Request-Monitor, Web-Stat-Compresion, Web-Filtering, Web-Windows-Auth, Web-Net-Ext45, Web-Asp-Net45, Web-ISAPI-Ext, Web-ISAPI-Filter, Web-WebSockets, Web-Mgmt-Console, Web-Mgmt-Service, NET-Framework-45-Core, NET-Framework-45-ASPNET, NET-WCF-TCP-PortSharing45, Server-Gui-Mgmt-Infra, SErver-Gui-Shell, PowerShell, PowerShell, PowerShell-V2, PowerShell-ISE, WAS-Process-Model, W0W64-Support -Restart

The install may take some time; go grab a coffee in the meantime.

Assigning the Service Account for Clarity Web Gateway to Use

During the pre-install process, a Service Account was created. On the Application Server, the Service Account must be granted the proper permissions. These steps must be done on every Application Server. There are two options:

Option 1: Minimal Permissions

  1. Add full permission for the Service Account to access the private key of each certificate from the pre-install guide.
    1. Open MMC on the application server.
    2. Extend the File tab and click on Add/Remove Snap-in.
    3. Choose Certificates from the left panel and press Add.
    4. Click OK and the window will close.
    5. Double-click on Certificates in the middle window.
    6. Double-click on Personal and then Certificates.
    7. On the Certificate(s) used to enable HTTPS on the Web Gateway API/Admin website, right-click, select All Tasks, then Manage Private Keys.
    8. Click Add.
    9. Enter the Service Account username, {Service User}, and click OK.
    10. Ensure that the Service Account is selected in the list and make certain the Read -> Allow box is checked.
    11. Click OK.
  2. Add the Service Account to the application server’s IIS_IUSRS group.
    1. Open MMC on the application server.
    2. Expand the File tab and click on Add/Remove Snap-In.
    3. Choose Local Users and Groups on the left panel and click Add.
    4. Select Local Computer and click Finish.
    5. Press OK and the window will close.
    6. Double-click on Local Users and Groups and then Groups.
    7. Right-click on the IIS_USRS group and press the Add button.
    8. Enter the Service Account user name, {Service User}, and click OK.
    9. Press OK again to close the window.

Option 2: Local Administrator

  1. Grant the Service Account read/write permissions for the folder where Content files will be stored.
    This is especially important when the folder is on a network share.
  2. Make the Service Account a local Administrator on the application server by adding the service account to the local administrators group in Windows Server. Do the following:
    1. Open Run and type COMPMGMT.MSC.
    2. Under Users and Groups click Groups.
    3. Double-click on Administrators.
  3. Click Add and then search for and add the Service account user name, {Service User}.
  4. Click OK to close the window.

SQL Administrator

Create the Login for the Service Account on the Database Server

You will need to create the login for the Service Account on the Database Server. This will allow the Service Account to log in to the database. For assistance with this, please see the Microsoft documentation available at: http://technet.microsoft .com/en-us/library/aa337565.aspx.

Create the Web Gateway Database

Use SQL Server Management Studio to connect to the SQL Server that the Web Gateway will use.

→If not already completed, record the Server name from the above dialog as {Database Server} on the Configuration Worksheet.

Once connected, run the following SQL statement to create an empty database for Web Gateway using the {Database Name} from the Configuration Worksheet as the database name:

CREATE DATABASE {Database Name}

Ex. CREATE DATABASE CcMain_Wg

Grant Database Permissions to the Service Account

While still connected to the Database Server in SQL Server Management Studio, run the following SQL statements to grant permissions to the Service Account as db_owner for the database:

USE {Database Name}

CREATE USER [{Service User}] FOR LOGIN [{Service User}] WITH DEFAULT_SCHEMA=[dbo]
GO

ALTER AUTHORIZATION ON SCHEMA::[db_owner] TO [{Service User}]
GO

EXEC sp_addrolemember N'db_owner', '{Service User}'
GO

Ex:
USE CcMain_Wg

CREATE USER [webgateway\webgatewaysvc] FOR LOGIN [webgageway\webgatewaysvc] WITH DEFAULT_SCHEMA=[dbo]
GO

ALTER AUTHORIZATION ON SCHEMA: :[db_owner] TO [webgateway\webgatewaysvc]
GO

EXEC sp_addrolemember N'db_owner', 'webgateway\webgatewaysvc'
GO

Clarity Web Gateway Installer

Please verify that all of the above tasks have been completed and that the Configuration Worksheet has been completed in full. Failure to do so may result in errors when going through the Clarity Web Gateway installation steps listed in the Web Gateway Install Guide.

Step 1: Run the Clarity Web Gateway Database Installer

Log in to the database server as a user with read, query and create/alter table rights (db_owner equivalent) on the runtime and data warehouse databases.

IMPORTANT: If you are installing a single server with a single instance configuration and are using a local directory path to store media (not a network share), you must run the database installer on the application server in order for the content files to be staged

properly. You will need to be logged into the application server as someone with db_owner rights on the databases and as a local administrator.

Run the Clarity Web Gateway Database Installer, entering the parameters recorded in the Clarity Web Gateway Configuration Worksheet.

After you enter the database server and name the installer will check the state of the database to make sure it is an empty database and that a new install can proceed.

The section below shows a screenshot of the installer and which Clarity Web Gateway Configuration Worksheet Parameter is needed in each field

Installer Dialog Worksheet Parameters
 
Database Server
Database Name
Host Websites
Lync Autodiscover Service
Connect Admin Website Hostname
API and Content Site Hostname
API and Content Site SSL Thumbprint
Content Share Path
Admin Site Hostname
Admin Site SSL Certificate Thumbprint
Service User
Low Permission User
Instance Name

Once the Database Installer has completed successfully, proceed to the next step. An installation log will be created and placed on the desktop. It is recommended to review this installation log if any errors occur to troubleshoot the potential cause.

Step 2: Run the Clarity Web Gateway Application Server Installer

Log in to the application server as a user with local admin rights on the app server and query permissions on the database.

Run the Clarity Web Gateway Application Server Installer, entering the server and name of the database found in the configuration worksheet.

The Application Server Installer will query the database and use the configuration values entered during the Database Installer to configure the Application Server.

The Application Server Installer will also detect if the database is set up for a new install; if not it will prompt you to exit the installer and run the Database Installer before proceeding.

Worksheet Parameters are listed in purple. Bold orange parameters are server specific parameters for the server you are running the installer on. They are found on the worksheet under the “Server Specific” section.

Installer Dialog Worksheet Parameters
 
 
Database Server
Database Name
Multiple Servers
Service User Password
Low Permission User Password
API and Content Site SSL Certificate Thumbprint
API and Content Site IP Address (for this server)
Admin Site SSL Certificate Thumbprint
Admin Site IP Address (for this server)

Step 3: Verify Load Balancing Settings for Multi-Server Deployments

If configured for High-Availability or in a Load-Balanced setup, the load balancing should be done through an F5 (or equivalent Skype-certified) load balancer. We do not recommend DNS load balancing because it cannot support automatic failover in the event of a server failure, but it is a supported load-balancing method.

The configuration should allow pass-through authentication using Windows authentication (not using One-Connect on F5 or the equivalent or other systems) for the Admin site (not needed for the API site) and balancing on ports 8o (http) and 443 (https). We recommend the entry should be configured with fewest connection scheduling and have 10 minute source IP persistence. In larger installations, more advanced setups may be configured.

For the API site, the load balancing configuration should support WebSocket connections for maximum performance. If WebSockets are unavailable, the API will seamlessly revert to long-polling.

Step 4: (Optional) Disable HTTP for Sies

By default the installer sets the IIS websites created for the API and the admin website to have both http and https bindings. However, for security purposes you may want them reachable only by https. To do this, perform the following steps on each application server:

  1. Open IIS Manager.
  2. Select the Web Gateway site.
  3. Double-click on SSL Settings.
  4. Check Require SSL.
  5. Click Apply.

Step 5: (Optional) Deploy Forms Authentication

The standard Clarity Web Gateway deployment is configured to authenticate users using integration Windows authentication. This gives users the most streamlined, native, and easy-to-use functionality possible. In some cases however, it is not possible or reasonable to use Windows integrated authentication. In these cases where your Connect instance already uses Forms authentication, Web Gateway can use Forms authentication as well to authenticate through Connect if Connect has already set up for forms auth. Simply follow these steps:

  1. On each application server that is hosting the website component, make the following changes to the web.config file found at the root of the website (use IIS manager for easy access):
    1. In the <system.web> XML block, comment out the Windows authentication entry, and uncomment the 3 lines of the Forms authentication entry.
    2. In the <appSettings> XML block, change the WindowsAuth value from “true” to “false”.
  2. Go to the site in IIS Manager.
    1. Go to the Authentication Settings.
      1. Enable Anonymous Authentication.
      2. Disable Windows Authentication (if it is still enabled).
      3. At this point Anonymous and Forms Authentication should be enabled.
  3. Restart the IIS website.

Known Issues and Post-Install Steps

  • Please keep copies of the installer you used. They may be helpful later for troubleshooting.
  • We recommend disabling logging in IIS to avoid the IIS logs taking up too much disk space.
  • If you see authentication issues or database errors in the log when connecting to the admin site, look at the Web Gateway Application Pool in IIS Manager on each Application Server, under Advanced Settings and make sure the “Load User Profile” setting is True. If it is False, flip it to True, restart the Application Pool and the Web Gateway Sites.
    • If you are using Windows Authentication and the Web Gateway admin's Agent Profile is setup with “domain\username” as the Login Name, try changing it to just “username”, saving the Profile, closing your browser and then trying the admin site again.
  • If when loading the Template page on the Admin site, you do not see the images, check the JavaScript console and/or Developer Tools in your browser and see if you are getting any 401 Not Authorized errors.
    • If so, go to IIS, go the \Content virtual directory of the site, click on Authentication and configure Anonymous Authentication. Re-enter the Low Permission User Credentials, restart the website and try again.

Multi-Server Deployment Upgrades

From an installer standpoint, the only thing you have to do to deploy a multi-server instance of Web Gateway is to check the appropriate box in the application installer. However, there may be cases where you desire to take a currently deployed single-server instance and make it into a multi-server one. Any new servers you add can be made multi-server by using the installer and following the post-install steps, but for the instance already created you will need to perform the following manual configuration steps:

  1. On the application server where the API is installed, open IIS and click on the Web Gateway website and them press Stop to shut it down.
  2. Right-click on the application labeled API and select Explore to open a file explorer to the root directory.
  3. In this directory there will be a web.config file. Open it with a text editor running under administrative permissions (or another account with write access to the file).
  4. Under the <app settings> XML block find the key entitled UseBackplane and set its value to true. Save and close the file.
  5. In IIS, press the Start button on the Web Gateway website to start up the site again.

Version Upgrades

1.0 to 1.1

To upgrade from version 1.0 to 1.1, you should first make sure to fill out an updated Configuration Worksheet with the values you'll need for the 1.1 install. You can use your 1.0 Configuration Worksheet as a starting point and you will only have a few new fields to fill out.

Once you have an updated Configuration Worksheet, you should then uninstall Web Gateway 1.0 from the Application Servers. You can do this using Add/Remove Programs in the Control Panel. Once the uninstall is complete, you will have to manually clear out the following:

  • IIS Application Pool and websites.
  • Log files.

The IIS objects can be removed from the IIS Manager or via the command line. The log files can be deleted.

At this point, if you have made NO customizations to the Chat Widget or Chat Box templates via the Web Gateway Admin site, you can delete the contents of your Content Share Path (shared content directory).

Now you can run the database installer against the database that needs to be upgraded. It will prompt you for a few new values and then run all the scripts necessary to upgrade the database, as well as copying over new scripts and files to the Content Share Path.

Finally, you can now run the application installer on the application server(s) and follow the prompts. This will complete your upgrade from 1.0 to 1.1.

*** If you are upgrading a live instance of 1.0, once the upgrade is complete, you will have to

update the HTML Snippet in any host pages on your public website as that changes slightly with 1.1 ***

Uninstall, Repair, Modify

Uninstall

Clarity Web Gateway can be uninstalled using the Add/Remove Programs Control Panel. This will uninstall the application files from the application server.

If uninstall from Add/Remove Programs is not working, run the Application Server Installer again, select the instance and select “uninstall”.

Post-Uninstall Cleanup

The uninstall process leaves behind the following objects on the application server. In future versions, we may streamline the uninstall process to remove these items as well.

  • Log files and web.config files.

These files can be manually deleted.

Repair and Modify

The Repair and Modify options found on some installers are disabled in Clarity Web Gateway, so plan carefully if you are planning to have certain application servers only run a subset of its components.

If necessary, you could uninstall Web Gateway from an application server and run a fresh Application Server installer to change the mix of components installed on that server.

Administrative Site Guide

Introduction

This guide is to show how an administrator can use the admin website to configure an instance of the Web Gateway.

Accessing the Website

The admin website can be configured to authenticate users either by Windows or Forms authentication. If configured to use forms authentication the website will use your Connect credentials After authentication, in order to use the website your Connect account will need to be in a role that grants Web Gateway access (admin).

Templating Page

The templating page allows an admin to customize the “look and feel” of a Web Gateway deployment to better

match their company's branding as well as a place to get the HTML snippet that will need to be added to your website in order to enable web chat.

Colors

The Colors section of the page allows you to modify the color values of some elements o1 the chat experience.

  1. Primary Color — The primary color value controls the color of the chat box ribbon, attendant and agent speech bubbles, and the widget bubble. This color will be the most visible and widely used of the changeable colors so it is recommended you make this the brand's most recognizable color.
  2. Primary Font Color — The primary font color value controls the color of the text within the chat box attendant and agent speech bubbles as well as the widget bubble.
  3. Secondary Color — The secondary color value controls the color of the user speech bubble.
  4. Secondary Font Color — The secondary font color value controls the color of the text within the user speech bubble.

Images

The Images section of the page allows you to swap out some of the stock images with custom ones. Uploaded images should be in Portable Network Graphics (.png) or JPEG (.jpg) format.

  1. Banner — The banner image is the image that takes up the top bar of the chat box. In order for the image to be sized correctly it should be about 512px x 55px in size. Slight variations on these dimensions (such as 5l2px x 51px) can be used without an issue. A larger or smaller size may be used if it maintains an aspect ratio of approximately 13:1.
  2. Icon — The icon image is the picture that is used in the center of the ribbon on the chat box and also as the center point of the widget that will appear on your website. From a design standpoint it is recommended you use an image of your company’s logo or trademark here. A square image of any size will work as an icon. However, be aware that the corners of the image will be clipped when rendered as a circle.
  3. Attendant Icon — The attendant icon image is the picture that appears on the right side of messages sent by the attendant (i.e. automated system messages). A square image of any size will world as an icon. However, be aware that the corners of the image will be clipped when rendered as a circle.
  4. Agent Icon — The agent icon image is the picture that appears on the right side of messages sent by a Skype agent. Be aware that if you enable the option to use agent Skype pictures (described in greater detail in a later section) the Skype picture will overwrite whatever you set here. A square image of any size will work as an icon. However, be aware that the corners of the image will be clipped when rendered as a circle.
  5. Customer Icon — The customer icon image is the picture that appears on the left side of messages sent by the customer. A square image of any size will work as an icon. However, be aware that the corners of the image will be clipped when rendered as a circle.

Chat Box AND Widget Views

The chat box and widget views of the template page gives you a representation of what your chat experience currently looks like. When you use the page controls to alter colors or images these changes will be dynamically reflected by these views to give you an accurate look at what your changes will mean to the actual design. This makes customizing your chat a pain-free experience.

HTML Snippet

The HTML snippet control is where you get the markup needed to add the widget to your company’s website. Simply copy the text from the text area and paste it into an appropriate location on your website. If your website was created using a framework (such as ASP.NET) it is recommended that you put this snippet into a shared view that is used by all pages so you don't have to paste it on every page of the site.

Settings Page

The settings page contains several important settings that allow the Web Gateway to function properly. Normally you should only have to alter these values after the product is first installed but before it is deployed on the customer facing website. The corresponding Configuration Worksheet names for these values are in purple.

  1. Settings Cache Interval — The amount of time (in seconds) between attempts by the service to get the latest settings from the database. It is recommended that you do not change this value without guidance or approval from Support. However, if you do decide to alter the value it is not recommended to drop it below 20 seconds.
  2. Open Status Cache Interval — The amount of time (in seconds) between attempts by the service to get the latest queue information from the Connect web service. It is recommended that you do not change this value without guidance or approval from Support. However, if you do decide to alter the value it is not recommended to drop it below 20 seconds.
  3. Log Level Lifetime — The amount of time (in days) that log files will persist until they are automatically deleted.
  4. Log Level — The level at which logging statements from the service and website will be saved to a log file. Debug level results in the most logs being captured, while Fatal results in the least. Generally you should keep the log level at Warn or Error after the product has been first installed and in use for a few days unless there is an issue and logs are needed for diagnosis.
  5. Lync Discovery URL (Lync Autodiscover Service)— The URL of the UCWA endpoint on your Skype server.
  6. Web Integration Address — The URL of the exposed Connect web endpoint that the Gateway interfaces with. Please make sure to include the “http://” in the URL.
  7. Gateway Service Address — The URL that the Gateway API will be accessible at. Please make sure to include the “http(s)://” in the URL. This corresponds to the API and Content Site Hostname plus http(s)://.
  8. Gateway Directory Address — The URL of the virtual directory that contains all of the Gateway web content. Please make sure to include the “http(s)://” in the URL.
  9. Gateway Directory Physical Path (Content Share Path) - The absolute file path of the virtual directory that contains all of the Gateway web content.
  10. Gateway Remote Website Domain (Host Websites) — The domain(s) that are allowed access to the Gateway API. Please note that unlike other settings, in order for the changes in this field to take effect after saving you must restart the service. This field can take one of the following values:
    1. *: All domains are granted access.
    2. A whitespace or comma delimited list of domains. It can contain as many domains as can fit in the 200 character limit. Acceptable values include examples such as “http://www.domain.com”, “http://domain1.com http://domain2.com”, or “http://domain1.com, http://domain2.com”. Make sure you preface the domains with the correct “http://” or “https://” value.
      ***If you update the Gateway Remote Website Domain, you must restart the Web Gateway sites in IIS for the new setting to be picked up ***
  11. Supported SignalR Transports — The transport protocols that the Web Gateway API will try to use. By default this is set to Web Sockets and Long Polling. If Web Sockets are not available, you can select just Long Polling to avoid failed attempts to connect to Web Sockets.

Website Mapping Page

The website mapping page is where you can set a variety of options that will be applied to the chat based upon the relative path of the URL that the chat request is initiated from. There will always be a default mapping (denoted by "*") that will be used in any instance where no other match exists. If you want to use a different set of settings for a specific page or pages, however, you can create a new mapping with a URL that will match the desired page(s). For example, you could set up a mapping for the string “demo-request”. If a chat session is initiated from the website page “yourdomain.com/demo-request” the settings from the new mapping will be used instead of the default one. If multiple mappings match a page the longest match will always be chosen.

Adding a Mapping

You can create a new mapping by clicking the add button on the top of the website mapping page. The new mapping will have all the default settings copied to it with the exception of the associated queues. This makes it easy to just make a few changes from the default settings. You cannot add a new mapping with the same URL as another mapping.

Due to the large amount of customization there are several categories of settings that can be customized, each with several settings.

Context Settings

Context settings refer to the items that you may ash a user to provide before initiating a chat session. The Web Gateway currently allows you to ask for five pieces of information:

  1. Category — Ask the user to select a category from a provided list. The Category is synonymous with a Connect queue. When a user completes the context gathering phase of a chat session the chosen category dictates what queue the session will be routed to in Connect. The user will always be prompted to select a category unless only one category is associated with a mapping; in this case the category will automatically be selected. Unlike other types of context, prompting for a category cannot be disabled or made optional.
  2. Name — Ask the user to input their name.
  3. Email — Ask the user to input their email address.
  4. Phone Number — Ask the user to input their phone number.
  5. Question — Ask the user to input a tree form question.

Each setting can have their display same edited to present it to the user in a different manner. Additionally, with the exception of category you can choose whether to ask for the information at all, and if so decide if you want the context to be optional. Optional context allows the user to provide a blank answer to move past the question.

Associated Queues

The Associated Queues pane lets you choose which Connect Queues a user should be allowed to choose from when asked to select a Category during a chat session. The Queue’s Public Name is used as the Category.

Queues in the left box are NOT associated with the mapping, Queues in the right box are associated. Queues can be moved to and from each side via the arrow buttons in the center of the page.

In the configuration shown in the screenshot below, a user in a chat session will be prompted to choose one of three categories: General Questions, Sales or Products.

Widget Settings

The widget settings pane allows you to alter a few characteristics of the widget that will appear on your website. While you can enter the normal maximum of 200 characters into the widget message text for design reasons it is recommended you keep the message short, preferably under 30 characters.

  1. Display Corner — The corner of the website in which the widget will display itself.
  2. Open Message — The text that is displayed by the widget when at least one associated queue is open for chat.
  3. Closed Message — The text that is displayed by the widget when no queues have been associated with a mapping, all associated queues are currently closed or the whole portal is closed.
  4. Display When Closed — If this checkbox is not ticked, then the widget will simply not appear when all associated queues are currently closed. The default behavior is for this checkbox to be ticked and the widget to appear and display the Closed Message.
  5. Send To Call Flow — If this checkbox is ticked, then the widget will send a customer to the Connect Call Flow mapped to the incoming URL of “WebGateway” and not through the normal context gathering configured in Context Settings. If Send to Call Flow is ticked, the widget will display the Closed Message (or not appear) when no queues have been associated with a mapping, all associated queues are currently closed or the whole portal is closed.

Chat Box Settings

The chat box settings pane contains a collection of settings that can be changed to alter the behavior of the chat box.

  1. Inactivity Message Interval — The amount of time (in seconds) that a user is allowed to be idle before they receive an inactivity message to ash them if they are still there. Being “idle” is described as not sending a message or at least typing in the chat box.
  2. Inactivity Termination Interval — The amount of time (in seconds) that a user is allowed to be idle before they are disconnected from their chat session. Set this to a lower value than the Inactivity Message Interval if you just want them to be disconnected without receiving an inactivity message.
  3. Default User Name — The name given to a customer before they enter and confirm their name via a context setting. This name is below each customer speech bubble. If a mapping is not configured to prompt for a name this value will remain as their name for the chat session.
  4. Attendant Name — The name used to represent the attendant of a session. This value is displayed above each attendant speech bubble.

Attendant Messages

The attendant is a way of automatically displaying certain system messages to the user. They are mostly used to

convey the state of the conversation to the user.

  1. Welcome Message — The message displayed when a user first navigates to the chat box.
  2. Error Message — The message displayed when an error has occurred in a chat session. Generally the user should be told there was an error and to try to refresh the chat window to start another session.
  3. Context Transition Message — The message displayed after the user has entered all the required context and the Gateway has begun the process of connecting to a chat session.
  4. Inactivity Message — The message displayed when the user has been inactive longer than the period specified by the Inactivity Message Interval setting.
  5. Category Closed Message — The message displayed when the Gateway makes a chat request to a Connect queue and Connect responds that the requested queue is closed. This should be a rare occurrence that should only happen when the open status of the queue changes since the last time the Gateway fetched the status from Connect.
  6. Closed Message — The message displayed when a user navigates to the chat box but there are no queues available to chat with. Most instances of this should be caught by the chat widget appearing in its closed state, but this is here in order to catch cases that occur very quickly after queue open statuses change.
  7. End Message — The message displayed when a session has ended.

Context Messages

Context messages are a subset of attendant messages that are specifically to request input from the user.

  1. Category Message — The message displayed when the user is asked to choose a category.
  2. Name Message — The message displayed when the user is asked to enter their name.
  3. Email Message — The message displayed when the user is asked to enter their email.
  4. Phone Message — The message displayed when the user is asked to enter their phone number.
  5. Question Message — The message displayed when the user is asked to enter their question.
  6. Validation Error Message — The message displayed when the entered value for a context setting fails validation (i.e. a phone number contains a letter, name contains a number, etc.).
  7. Context Confirmation Message — The message displayed when the user finishes entering all the required context and they are asked to confirm everything they entered is correct.
  8. Incorrect Context Message — The message displayed when the user has indicated one of their inputs is incorrect.

Web Gateway Advanced Usage

Introduction

For customers that do not want to use the Web Gateway widget, this guide describes the Direct URL feature and JavaScript Client Library available for initiating web chats using Web Gateway 1.1. These offer a greater level of control, but require some effort from customer integrators, who must be familiar with websites, HTML and JavaScript.

Direct URL Access

Integrators can use the Web Gateway Direct URL to open the Web Gateway chat box in a new window, bypassing

the Web Gateway widget entirely. Any questions configured in the Context Settings page on the Web Gateway Admin site are then asked by the chat box.

FINDING THE DIRECT URL

The Direct URL is the API URL for the Web Gateway with “/content/Html/ChatBox.html” appended to it. For example, if the Web Gateway is accessible from the URL of https://webgatew ay. clari ty con.com, then the Direct URL is http s://webg atew ay. clarity con.com/content/ Html/ChatBox.html.

OPENING THE DIRECT URL

The most straightforward way to open the Direct URL and get the customer into the web chat is to open a new browser window using JavaScript's window.open function (https://developer.mozilla.org/en-US/docs/Web/API/Window/open).

Query String Parameters

An integrator can append one or more query string parameters to the Direct URL in order to unlock additional functionality.

URL

The URL query string parameter is used to provide the chat box with the URL of the page that it was opened from. The chat box uses this value to determine which Website Mapping from the Web Gateway admin site to use to load settings, such as Context Settings for the chat session. If this query string is not present the default mapping will be used.

***The value placed in this parameter needs to be encoded by the native function encodeURIComponent (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) in order for everything to function properly.***

Example:
https://webgateway.claritycon.com/content/html/ChatBox.html?url=http%3A%2F%2Femployees.claritycon.com%2Fwebgateway

Queue ID

The queue id query string parameter is used to programmatically override which Connect queue the user should be placed in. If this id is set to a valid queue, the chat box will skip over the portion of context gathering in which the user is prompted to choose a category and instead simply use the provided value. This can be a very useful technique if a customer desires to determine what queue to place a customer into based off of criteria other than the page URL.

Example:
http://webgateway.claritycon.com/content/html/ChatBox.html?queueId=2

SPECIAL CASE: QUEUE ID = -1

The queue id parameter can also be set to a special value of -1. This will trigger the chat box to skip gathering context entirely and simply place a chat to the Connect Call Flow mapped to the Incoming URI of “WebGateway”.

Example:
http://domain.claritycon.com/content/html/ChatBox.html?queueId=-1

Known Issues

If you specify an invalid Queue Id in the Direct URL, such as Queue Id 9 when you have just two Queues, the web chat user will be put on hold, but stuck there until they hang up. This web chat will not show up in the Dashboard.

Client Library

Integrators can further adapt Web Gateway to their website's needs by using the client library. The purpose of this

library is to allow developers to programmatically obtain information about their web gateway instance.

Finding the Client Library

The Client Library is located at the API URL for the Web Gateway with “/content/scripts/client/webgateway.clientLib.js” appended to it. For example, if the Web Gateway is accessible from the URL of https://webgateway.claritycon.com, then the Direct URL is https://webgateway.claritycon.com/content/scripts/client/webgateway.clientLib.js.

Using the Client Library

Dependencies & Loading the Library

In order for the library to function the page must include dependency scripts before the library script. These dependencies are:

  1. jQuery 1.6.4+ - Include from whatever location suits you best.
  2. jQuery.SignaIR 2.1.2 — Located at {API URL}/content/scripts/lib/jquery/jquery.signaIR-2.1.2.min.js
  3. Web Gateway Hub — Located at {API URL}/signaIr/hubs

If these dependencies are not included in a page before the client library file, the library will throw exceptions when loading that state which dependency is missing. And of course, remember to include the library itself in a script tag.

Example:
<script type="text/javascript" src—"https://code.jquery.com/jquery-1.11.1.min.js"></script>
<script type="text/javascript" src-"https://webgateway.claritycon.com/content/scripts/lib/jquery/jquery.signalR-2.1.2.min.js"></script>
<script type="text/javascript" src-"https://webgateway.claritycon.com/api/signalr/hubs"></script>
<script type="text/javascript" src-"https://webgateway.claritycon.com/content/scripts/client/webgateway.clientLib.js"></script>

Methods

getDirectUrl
This function provides the direct URL of the chat box (without query string arguments).

Example:
var client = new webGateway.clientLib();
var url = client.getDirectUrl();

getStatus
This function provides the open/closed status of the Web Gateway for the page the script is loaded on. If this page isn't configured as a separate mapping, the open/closed status for the default mapping will be returned.

Example:
var client = new webGateway.clientLib();
client.getStatus()
.done(function(isOpen){

console.log(isOpen);

})
.fail(function(){

console.log("Failed to get open/close status');

});