Gladly

Gladly

The Gladly Glad App is an embeddable UI element that lives on your website and allows customers to search for answers or talk and interact with your team in real-time. The Gladly Glad App API enables you to have programmatic control of the Gladly Glad App.

JavaScript snippet

Add the following JavaScript embed code to all your site’s pages, preferably at the bottom of the page to avoid slowing down the main page content to load. This will load the code that powers the Gladly Glad App on your site.

Note that the fourth argument of the snippet below specifies 'PROD' which enables you to use the latest release of the Chat-SDK with your production appId.

 <script>
  !function(c,n,r,t){if(!c[r]){var i,d,p=[];d="PROD"!==t&&t?"STAGING"===t?"https://cdn.gladly.qa/gladly/chat-sdk/widget.js":t:"https://cdn.gladly.com/chat-sdk/widget.js",c[r]={init:function(){i=arguments;var e={then:function(t){return p.push({type:"t",next:t}),e},catch:function(t){return p.push({type:"c",next:t}),e}};return e}},c.__onHelpAppHostReady__=function(t){if(delete c.__onHelpAppHostReady__,(c[r]=t).loaderCdn=d,i)for(var e=t.init.apply(t,i),n=0;n<p.length;n++){var a=p[n];e="t"===a.type?e.then(a.next):e.catch(a.next)}},function(){try{var t=n.getElementsByTagName("script")[0],e=n.createElement("script");e.async=!0,e.src=d+"?q="+(new Date).getTime(),t.parentNode.insertBefore(e,t)}catch(t){}}()}}
  (window,document,'Gladly','PROD')
 </script>

Initialize

In order to start the Gladly Glad App on your site, you must initialize it after you load the above JavaScript embed code.

Basic Initialization:

Add the following script tag to your page to automatically initialize the Gladly Glad App. This is most appropriate if you do not want to take advantage of any Gladly API functionality and just want to display a basic widget. The "your-own-id" value can be found in the Settings > Glad App page in Gladly under the "Embed Name" column.

<script>
 window.gladlyConfig = {
   appId: 'your-own-id'
 };
</script>

Manual Initialization:

Glad App can be manually initialized to get better control over when to display the Glad App. This could be desirable, for example, if you want to start the Glad App from your own button.

For a more dynamic interaction, Glad App exposes an Availability state that allows the site to change the behavior depending on if chat is closed or if it's unavailable due to high demand.

The example below initializes the Glad App, then checks to see if chat is available and sets a class on a button assumed to exist on the page.

Gladly.init({
  appId: "your-own-id"
}).then(function() {
  // This is called once Glad App has been initialized.

  // An element with the id "start-chat" is assumed to be on the page.
  var startChatButton = document.getElementById('start-chat');

  // An onClick handler can be attached to the "start-chat" element
  startChatButton.onclick = function() {Gladly.show()};

  // This API call gets the current availability
  var availablility = Gladly.getAvailability();

  // Setting the availability as the class name on the "start-chat" element,
  // this allows us to change the look of the button via CSS.
  startChatButton.setAttribute('class', availablility.toLowerCase());

  // Subscribe to changes in availability, and update the class on the "start-chat" element.
  Gladly.on('availability:change', function(availablility) {
    startChatButton.setAttribute('class', availablility.toLowerCase());
  });
}).catch(function(error) {
  // If anything goes wrong when Glad App is being initialized, this gets called.
  console.log('error:', error)
});

Browser Support

The Gladly Glad App supports major browsers. For the desktop, we support current + previous major versions of Chrome, Firefox, and Safari along with the current version of Microsoft Edge. For mobile, we support current + previous major versions of Chrome on Android and iOS and the current + previous versions of Safari on iOS.

Working with Sandbox / Staging Environment

You can use our sandbox environment to test upcoming Chat-SDK releases or new configuration on your staging site. To launch the Gladly Glad App on your staging site, follow the steps above to add the JavaScript embed code and initialize. Then make following modification:

Change the value in this part of your embed code to 'STAGING':

    (window,document,'Gladly','STAGING')

Working with Single-Page Applications

If your website is a single-page application, you will need to call the navigate method every time the user navigates to another page on your site so that Gladly can re-evaluate proactive chat settings and Glad App display rules.

Deployment Checklist

  1. Add embed code to correct environment
  2. Add embed code only once to each page
  3. Initialize the Glad App by either defining window.gladlyConfig OR calling Gladly.init(), never both

Custom Minimized Button

Gladly allows you to customize the minimized chat button that is rendered on your site to better align with your brand. Examples and documentation can be found here

Content Security Policy

Content-Security-Policy (CSP) is an advanced added layer of security that helps detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. For websites that make use of CSP the following directives has to be added to make Glad App work as expected:

Production Environment

connect-src https://chat-assets.cdn.gladly.com https://chat-sdk.cdn.gladly.com https://cdn.gladly.com https://us-1.gladly.com https://api.us-1.gladly.chat wss://ws.us-1.gladly.chat https://api.smooch.io https://*.config.smooch.io wss://api.smooch.io https://gladly-production.sinter-collect.com https://js.verygoodvault.com https://js2.verygoodvault.com;
frame-src https://js.verygoodvault.com https://js2.verygoodvault.com;
img-src blob: https://chat-assets.cdn.gladly.com https://media.cdn.gladly.com https://media.smooch.io;
media-src https://chat-sdk.cdn.gladly.com https://cdn.gladly.com;
script-src 'unsafe-inline' https://chat-sdk.cdn.gladly.com https://cdn.gladly.com https://cdnjs.cloudflare.com https://api.smooch.io https://js.verygoodvault.com https://js2.verygoodvault.com;
style-src 'unsafe-inline' 'self' https://chat-sdk.cdn.gladly.com https://cdn.gladly.com;

Sandbox / Staging Environment

connect-src https://chat-assets.cdn.gladly.qa https://chat-sdk.cdn.gladly.qa https://cdn.gladly.qa https://us-uat.gladly.qa https://api.us-uat.gladly.chat wss://ws.us-uat.gladly.chat https://api.smooch.io https://*.config.smooch.io wss://api.smooch.io https://gladly-staging.sinter-collect.com https://js.verygoodvault.com https://js2.verygoodvault.com;
frame-src https://js.verygoodvault.com https://js2.verygoodvault.com;
img-src blob: https://chat-assets.cdn.gladly.qa https://media.cdn.gladly.qa https://media.smooch.io;
media-src https://chat-sdk.cdn.gladly.qa https://cdn.gladly.com;
script-src 'unsafe-inline' https://chat-sdk.cdn.gladly.qa https://cdn.gladly.qa https://cdn.gladly.com https://cdnjs.cloudflare.com https://api.smooch.io https://js.verygoodvault.com https://js2.verygoodvault.com;
style-src 'unsafe-inline' 'self' https://chat-sdk.cdn.gladly.qa https://cdn.gladly.qa https://cdn.gladly.com;

Methods

(inner) init()(config) → {Promise}

This method initializes the Glad App on your site using the ID specified in the config parameter. It returns a promise that will resolve when the Glad App is ready.

Note that init must be called, and the initialization must fully complete (which is signaled when the returned promise is resolved) before calling any other api methods.

Example:

Gladly.init({ autoShowButton: true, appId: "your-app-id" });
Parameters:
Name Type Description
config Gladly.SidekickConfig

Glad App configuration

Returns:
Type
Promise

(inner) getAvailability()() → {Gladly.Availability}

This method returns the current chat Availability

Example:

Gladly.getAvailability();
Returns:
Type
Gladly.Availability

(inner) on()(eventName, observer) → {function}

This method subscribes an observer to eventName and returns an unsubscribe function.

Example:

Gladly.on("availability:change", (availability) => { console.log(`New availability: ${availability}`)});
Parameters:
Name Type Description
eventName String

The name of the event to subscribe to

observer function

Observer function to be invoked when event triggers

Returns:
  • The function to remove the newly added observer function
Type
function

(inner) show()()

This method displays the Gladly Glad App when called.

Example:

<button onClick="Gladly.show()">Start Chat</button>

(inner) setUser()(user)

This method is used to set the user in Glad App, when a user is set the end user does not have to provide name and email. If a user is already set, an error will be thrown. A user can be identified either by an email address or by a User Identity JWT token, not both.

Examples

Setting user by email and name

Gladly.setUser({ "John Smith", "john.smith@example.com" });

Setting user with a JWT.

Gladly.setUser({ "John Smith", jwt: async () => "<User Identity JWT" });
Parameters:
Name Type Description
user Object

user object

Properties
Name Type Description
name string

The name of the user. This is optional when a JWT is provided

email string

The email of the user.

jwt string | function

A User Identity JWT token or a async function that returns a User Identity JWT token.

(inner) getUser()() → {Gladly.User|undefined}

This method is used to get the user. If the user does not exist, it will return undefined.

Example
Gladly.getUser();
Returns:

User object or undefined if user does not exist

Type
Gladly.User | undefined

(inner) clearUser()() → {Promise.<void>}

This method is used to clear the current user

Example
Gladly.clearUser();
Returns:

Promise that resolves when user has been fully removed.

Type
Promise.<void>

(inner) navigate()()

This method is used to notify the Glad App when your website navigates without reloading the page. Gladly will read the updated location from 'document.location.href'.

Most common use for this would be if you have a single page application and you have rules configured to control what pages the Glad App is displayed on.

Example:

Gladly.navigate();

(inner) applyCampaign()(campaignId)

Will be executing the actions of a specific campagin. If "campaignId" does not exist an error will be returned. To be used in conjunction with the the "campaign:triggered" event, where the campaignId will be found.

Example:

Gladly.applyCampaign('<campaign-id>');
Parameters:
Name Type Description
campaignId String

The id of the campaign that should be applied.

Type Definitions

SidekickConfig

Properties:
Name Type Description
appId string

id specifying your own application

autoShowButton boolean

boolean specifying whether the Glad App button will automatically show on load, default value is false. Formerly autoShowWidget (still supported for backwards compatibility)

Type:
  • Object

User

Properties:
Name Type Description
name string

user name

type Gladly.UserType

the type of user

identityType string

EMAIL

identity string

email address if identityType is EMAIL

hasOpenConversation boolean

TRUE if user has an open conversation

Type:
  • Object

UserType

The different user types:

  • ANONYMOUS - User is anonymous, there is no identity of the user.
  • AUTHENTICATED - User has been set via setUser() method and a User Identity Token was provided.
  • SELF_IDENTIFIED - The end user has been set via setUser() without a User Identity Token, or the end user provided their identity themself in the conversation.
Type:
  • string

Campaign_Action

Properties:
Name Type Description
id string

id specifying the action

type Gladly.Campaign_Action_Type

type of action

content Object

action specific content

An action triggered by a campaign

Type:
  • Object

Greeting_Campaign_Action_Content

Properties:
Name Type Description
message string

message shown to the user

ignoreThrottling bool

indicates if ignoreThrottling is enabled

skipOnboarding bool

indicates if skipOnboarding is enabled

The content for a Greeting Action

Type:
  • Object

Availability

The different availability states that exist:

  • AVAILABLE: Chat agents are ready to receive new chat messages
  • UNAVAILABLE_OFFICE_CLOSED: Chat is unavailable due to office hours
  • UNAVAILABLE_BUSY: Chat is unavailable due to high demand
Type:
  • string

Campaign_Action_Type

The different campaign action types that exist:

  • GREETING: Proactive Chat campaign fired to present greeting to consumer
Type:
  • string

Conversation_Ended_Reason

The different conversation closed reasons that exist:

  • AGENT_ENDED: The chat agent has ended the conversation
  • TIME_OUT: There has been no activity in the chat within the configured time and conversation automatically closed
  • SWITCH_DEVICES: The same customer has started a chat conversation on a different device
Type:
  • string

Message_Type

The different message types that exist:

  • TEXT: a message of type text
  • IMAGE: a message of type image
  • FILE: a message of type file
  • QUICK_REPLY_REQUEST: a message containing a request for the user to enter a quick reply option
  • QUICK_REPLY_RESPONSE: a message containing a response to a quick reply request
  • CREDIT_CARD_REQUEST: a payment request asking to submit credit card information
Type:
  • string

Initiator_Type

The different initiator types that exist:

Type:
  • string

Quick_Action_Type

The different types of quick actions that exist:

  • ANSWER: an answer given inside of the Glad App
  • EXTERNAL_LINK: an external link that takes the customer to a new page
Type:
  • string

Sidekick_Open_Trigger

The different ways the Glad App can be opened that exist:

  • API: via an API call
  • BUTTON: via clicking on the chat icon
  • PROACTIVE_RULE: via a proactive rule
Type:
  • string

Events

availability:change

When availability changes, this event emits current availability.

Parameters:
Type Description
Gladly.Availability

Current availability

conversation:ended

Properties:
Name Type Description
source Gladly.Conversation_Ended_Reason

The reason the conversation was ended

When a conversation is ended, this event is emitted.

conversation:started

When a conversation is started, this event is emitted.

campaign:triggered

Properties:
Name Type Description
id string

id of the triggered campaign

actions Array.<Gladly.Campaign_Action>

array of action objects that result from the trigger

When a campaign is triggered, this event is emitted.

customer:onboarded

Properties:
Name Type Description
name string

The customer's name entered

email string

The customer's email address entered

When a customer finishes onboarding, this event is emitted.

message:received

Properties:
Name Type Description
type Gladly.Message_Type

Indicates the message type

initiatorId string

Indicates ID of message sender (e.g. agent id, rule id, api user id)

initiatorType Gladly.Initiator_Type

Indicates type of message sender

When a message is received by the consumer, this event is emitted.

message:sent

Properties:
Name Type Description
isInitialMessage boolean

Indicates if this is the first message from the consumer in the conversation

type Gladly.Message_Type

Indicates the message type

campaignId string

Indicates the campaign the message is in response to

When a message is sent by the consumer, this event is emitted.

quick-action:selected

Properties:
Name Type Description
label string

The label of the selected quick action

type Gladly.Quick_Action_Type

The type of the selected quick action

When a quick action is selected by the consumer, this event is emitted.

search:result-selected

Properties:
Name Type Description
label string

The label of the selected search result

When a search result is selected by the consumer, this event is emitted.

sidekick:closed

When the Glad App is closed by the consumer, this event is emitted.

sidekick:opened

Properties:
Name Type Description
source Gladly.Sidekick_Open_Trigger

The way the Glad App was opened

When the Glad App is open by the consumer, this event is emitted.