The Gladly Sidekick 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 Sidekick API enables you to have programmatic control of the Gladly Sidekick.
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 Sidekick 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 Sidekick 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 Sidekick. 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. Work with your Gladly CSM to get the “your-own-id” value.
<script>
window.gladlyConfig = {
appId: 'your-own-id'
};
</script>
Manual Initialization:
Sidekick can be manually initialized to get better control over when to display the Sidekick. This could be desirable, for example, if you want to start the Sidekick from your own button.
For a more dynamic interaction, Sidekick 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 Sidekick, 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 Sidekick 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 Sidekick is being initialized, this gets called.
console.log('error:', error)
});
Browser Support
The Gladly Sidekick 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 Sidekick 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 Sidekick display rules.
Deployment Checklist
- Add embed code to correct environment
- Add embed code only once to each page
- Initialize the Sidekick 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 Sidekick work as expected:
Production Environment
connect-src https://cdn.gladly.com https://us-1.gladly.com 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://media.cdn.gladly.com https://media.smooch.io;
media-src https://cdn.gladly.com;
script-src 'unsafe-inline' 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://cdn.gladly.com;
Sandbox / Staging Environment
connect-src https://cdn.gladly.qa https://us-uat.gladly.qa 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://media.cdn.gladly.qa https://media.smooch.io;
media-src https://cdn.gladly.com;
script-src 'unsafe-inline' 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://cdn.gladly.qa https://cdn.gladly.com;
Methods
(inner) init()(config) → {Promise}
This method initializes the Sidekick on your site using the ID specified in the config parameter. It returns a promise that will resolve when the Sidekick 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 | Sidekick configuration |
Returns:
- Type
- Promise
(inner) getAvailability()() → {Gladly.Availability}
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 Sidekick when called.
Example:
<button onClick="Gladly.show()">Start Chat</button>
(inner) setUser()(user)
This method is used to set the user from the user's name and email
Example:
Gladly.setUser({ name, email });
Parameters:
Name | Type | Description |
---|---|---|
user |
Gladly.User | Sidekick user object |
(inner) clearUser()()
This method is used to clear the current user
Example:
Gladly.clearUser();
Returns:
Promise that resolves when user has been fully removed.
(inner) navigate()()
This method is used to notify the Sidekick 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 Sidekick 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 sidekick button will automatically show on load, default value is |
Type:
- Object
User
Properties:
Name | Type | Description |
---|---|---|
email |
string | user email address |
name |
string | user name |
Type:
- Object
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:
- AGENT: represents a Gladly agent
- API: represents a Gladly API call
- AUTOMATION: represents a Gladly Rule
Type:
- string
Quick_Action_Type
The different types of quick actions that exist:
- ANSWER: an answer given inside of the sidekick
- EXTERNAL_LINK: an external link that takes the customer to a new page
Type:
- string
Sidekick_Open_Trigger
The different ways the sidekick 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 sidekick is closed by the consumer, this event is emitted.
sidekick:opened
Properties:
Name | Type | Description |
---|---|---|
source |
Gladly.Sidekick_Open_Trigger | The way the sidekick was opened |
When the sidekick is open by the consumer, this event is emitted.