Advanced chat customization

Updated 3 weeks ago by Gleb Billig

If you would like to further customize the chat widget, you can follow the instructions below. This article is meant to serve simply as a reference point for you and your team and following these instructions will require knowledge of HTML, JavaScript, and possibly Shopify Liquid.

The below video shows examples of three of the below Advanced Chat Customizations being installed into a Shopify theme.

If you're using BigCommerce, please keep in mind that BC has a 'Manage Code' feature that allows you to place only <script> codes. This means that you will be able to place the default chat code and only a few other customization codes there.
For any non-script codes, like the one for moving the widget up/down or left/right, you have to go into their 'Theme Manager > Edit Theme' and find the home.html file.
Disclaimer the suggestions below are not formally features of our chat widget, but suggestions on how to further customize it. We recommend for these steps to be performed by someone with a technical background as you're experimenting with the chat set-up.

Remove 'Powered by Gorgias' branding

You can remove the 'Powered by Gorgias' branding in the chat widget by adding this script to your webpage, before the script of the Gorgias chat:

<script>var HIDE_POWERED_BY_GORGIAS = true;</script>

Moving the chat to the left side

To move the chat to the left side of the web page, insert the following HTML code into the head section of your website:

<style>
#gorgias-chat-container iframe#chat-button { left: 22px }
#gorgias-chat-container iframe#chat-window { left: 0 }
#gorgias-chat-container iframe#chat-campaigns { left: 0 }
</style>

Changing the position of the chat widget

On Desktop

You can move the chat widget up on the page. If you want to do so, paste the HTML code below to move the chat widget up 50px (50 pixels). This will only be applied on desktop, and not on mobile so that you do not see issues with the chat window being printed outside phone screens.

<style>
@media (min-width: 768px) {
#gorgias-chat-container iframe {
margin-bottom: 50px !important
}
}
</style>
On Mobile

To move the chat widget up 50px (50 pixels) on mobile devices, please implement the following code:

<style>
@media (max-width: 768px) {
#gorgias-chat-container iframe#chat-button,
#gorgias-chat-container iframe#chat-campaigns {
margin-bottom: 50px !important
}
}
</style>

Hiding the chat on mobile

To hide the chat on mobile, add this code to your site: 

<style>@media (max-width: 768px) {#gorgias-chat-container {display: none}}</style>

The chat is conflicting with other widgets

If your chat widget is conflicting with other widgets, add this code to your site: 

<style>
#gorgias-chat-container iframe#chat-window,
#gorgias-chat-container iframe#chat-campaigns {
z-index: 2147483647 !important;
}
#gorgias-chat-container iframe#chat-button {
z-index: 2147483646 !important;
}
</style>

If you are using Shopify, the code needs to be added under theme.liquid files. It would be best if you add it somewhere close to the existent chat code, just for easier organization.

Subscribe to chat events

Sometimes it's useful to do something when the chat widget is open or closed. You can use the example below to do that. Notice that the code below uses window.setInterval - that is because the chat JavaScript code is loaded asynchronously and we don't know if it's loaded or not so we have to check periodically:

<script>
var gorgiasChatInterval = window.setInterval(function() {
if (window.GorgiasChat && GorgiasChat.hasOwnProperty("on")) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.
// the list of supported events is detailed below
GorgiasChat.on('EVENT_NAME', function(data) {
// your code should go here
});
}
}, 100);
</script>

Gorgias Chat supports the following events:

  • A ready event is triggered when the chat is rendered.
  • A destroy event is triggered when the chat is unmounted.
  • A message:received event is triggered when a message is received. The data parameter will contain the message attributes.
  • A message:sent event is triggered when a message is received. The data parameter will contain the message attributes.
  • A message event is triggered when a message is sent or received. The data parameter will contain the message attributes.
  • An unreadCount event is triggered when the unread message count changes. The data parameter will contain the new number of unread messages.
  • A widget:opened event is triggered when the chat window is opened.
  • A widget:closed event is triggered when the chat window is closed.
  • A connected event is triggered when a connection to the chat server is established.
  • A disconnected event is triggered when a connection to the chat server is lost.
  • A typing:start event is triggered when an agent begins typing their message.
  • A typing:stop event is triggered when an agent stops typing their message.

It is also possible to deregister an event listener using the GorgiasChat.off('EVENT_NAME', listener). The listener argument must be the function that was previously registered to subscribe to the event.

If you want to add a link on your page to open the chat when clicked, use the code below:

<a onclick="GorgiasChat.open();">Start a chat with our team</a>

Likewise, you can also have a link to close the chat:

<a onclick="GorgiasChat.close();">Close the chat</a>

Check if the chat is open or closed

You may use the following method to determine whether the chat is in an open or closed state:

GorgiasChat.isOpen() // will return true or false

Add custom CSS

If you wish to customize the visual aspect of the chat widget, you can add additional CSS rules to each of the three following sections: the chat button, the chat window, and the chat campaigns.

Add the following script to your web page and modify the three lines style.textContent = '...', replacing the content with your own CSS rules:

<script>
var maxRepetitions = 60
var repetitionCount = 0
var isWindowStyleAppended = false
var gorgiasChatInterval = window.setInterval(function() {
var container = document.querySelector('#gorgias-chat-container');
var chatButtonHead = container?.querySelector('#chat-button')?.contentWindow.document.querySelector('head');
var chatWindowHead = container?.querySelector('#chat-window')?.contentWindow.document.querySelector('head');
var chatCampaignsHead = container?.querySelector('#chat-campaigns')?.contentWindow.document.querySelector('head');

if (chatButtonHead?.children.length && chatWindowHead?.children.length && !isWindowStyleAppended) {
var buttonStyle = document.createElement('style');
buttonStyle.textContent = '.whatyouwanttochange {property: value}'; // the custom CSS for the chat button
chatButtonHead.appendChild(buttonStyle);

var windowStyles = document.createElement('style');
windowStyles.textContent = '.whatyouwanttochange {property: value}'; // the custom CSS for the chat window
chatWindowHead.appendChild(windowStyles);
isWindowStyleAppended = true;
}

if (chatCampaignsHead?.children.length) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.

var campaignStyles = document.createElement('style');
campaignStyles.textContent = '.whatyouwanttochange {property: value}'; // the custom CSS for the chat campaigns
chatCampaignsHead.appendChild(campaignStyles);
}

if (++repetitionCount == maxRepetitions) {
window.clearInterval(gorgiasChatInterval);
}
}, 100);
</script>

For example, if you wish to change the font used by the chat, you can set the following custom CSS:

styles.textContent = 'body { font-family: Helvetica, Open Sans, sans-serif !important; }'

Remove the chat based on country code

This feature requires an ipstack account. Free accounts are limited to 10,000 requests per month. If you exceed this limit, you will need to upgrade to a paid account.

If you only work with certain countries you might want to only treat chat messages from certain countries. The code below hides the chat for ALL countries except United States (US) and Mexico (MX)

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>
<script>
// set your ipstack API key
var ipstackAPIKey = 'YOUR_API_KEY'
// set your country code whitelist
var countryCodeWhiteList = ['US', 'MX']
// set this to false if you only have a free tier account for ipstack
var useHttps = true

function removeGorgiasChat(countryCode) {
var gorgiasRemoveChatInterval = window.setInterval(function () {
var container = document.querySelector('#gorgias-chat-container');
if (container && !countryCodeWhiteList.includes(countryCode)) {
window.clearInterval(gorgiasRemoveChatInterval); // this line breaks out of the loop - make sure it's not deleted.
container.remove()
}
}, 50);
}

var countryCode = window.localStorage.getItem('countryCode')
if (!countryCode) {
protocol = useHttps ? 'https' : 'http'
$.ajax({
url: protocol + '://api.ipstack.com/check?access_key=' + ipstackAPIKey + '&fields=country_code',
dataType: 'jsonp',
success: function (json) {
if (json && json.country_code) {
countryCode = json.country_code
} else {
countryCode = 'unknown'
}
window.localStorage.setItem('countryCode', countryCode)
removeGorgiasChat(countryCode)
},
error: function (request, status, error) {
console.error(request.responseText);
window.localStorage.setItem('countryCode', 'unknown')
removeGorgiasChat('unknown')
}
})
} else {
removeGorgiasChat(countryCode)
}

Check whether current time is in business hours

You may use the following method to determine whether the Chat business hours (as defined in the Helpdesk) - please note that this variable is only trustworthy after the Chat initialization:

GorgiasChat.isBusinessHours() // will return true or false

Remove the chat outside business hours

Add the following code to your website right before our widget installation script in order to hide the chat outside business hours.

<script>var HIDE_WIDGET_OUTSIDE_BUSINESS_HOURS = true;</script>

Adjust chat default text values

It is possible to adjust the hardcoded text values used by the chat. Simply update the values below in the dictionary containing the texts and insert the script in your HTML.

<script>
var dict = {
"introductionText": "How can we help?",
"offlineIntroductionText": "We'll be back tomorrow",
"actionPostbackError": "An error occurred while processing your action. Please try again.",
"clickToRetry": "Message not delivered. Click to retry.",
"conversationTimestampHeaderFormat": "MMMM D",
"fetchHistory": "Load more",
"fetchingHistory": "Retrieving history...",
"invalidFileError": "Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).",
"messageError": "An error occurred while sending your message. Please try again.",
"messageIndicatorTitlePlural": "({count}) New messages",
"messageIndicatorTitleSingular": "({count}) New message",
"messageRelativeTimeDay": "{value}d ago",
"messageRelativeTimeHour": "{value}h ago",
"messageRelativeTimeJustNow": "Just now",
"messageRelativeTimeMinute": "{value}m ago",
"messageTimestampFormat": "h:mm A",
"messageSending": "Sending...",
"messageDelivered": "Delivered",
"tapToRetry": "Message not delivered. Tap to retry.",
"unsupportedMessageType": "Unsupported message type.",
"unsupportedActionType": "Unsupported action type.",
"headerText": "Gorgias Team",
"inputPlaceholder": "Type a message...",
"emailCapturePlaceholder": "your@email.com",
"emailCaptureInputLabel": "Get notified by email",
"emailCaptureOnlineTriggerText": "Leave us your email and we will reply soon.",
"emailCaptureOnlineThanksText": "Thanks! We'll email you at {email} if you leave.",
"emailCaptureOfflineTriggerText": "We're away, leave us your email and we'll respond shortly.",
"emailCaptureOfflineThanksText": "Thanks {email}! We'll get back to you shortly.",
"emailCaptureRequiredEmailPlaceholder": "Leave your email",
"emailCaptureRequiredMessagePlaceholder": "Write your message",
"backLabelBackInAMinute": "Back in 1 minute",
"backLabelBackInMinutes": "Back in {value} minutes",
"backLabelBackInAnHour": "Back in 1 hour",
"backLabelBackInHours": "Back in {value} hours",
"backLabelBackInDays": "Back in {value} days",
"backLabelBackTomorrow": "Back tomorrow",
"campaignClickToReply": "Click to reply",
"poweredByGorgias": "Powered by Gorgias",
"send": "Send"
}

var gorgiasChatInterval = window.setInterval(function() {
if (window.GorgiasChat && GorgiasChat.hasOwnProperty("updateTexts")) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.
window.GORGIAS_CHAT_TEXTS = dict
GorgiasChat.updateTexts(dict)
}
}, 100);
</script>

Programmatically capture an email

You may want to set a user email programmatically. To do so, we exposed the `captureUserEmail` method that allows you to change the user email associated to the current chat conversation - please note that this variable is only trustworthy after the Chat initialization.

var gorgiasChatInterval = window.setInterval(function() {
if (window.GorgiasChat && GorgiasChat.hasOwnProperty("captureUserEmail")) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.
GorgiasChat.captureUserEmail('user@example.com');
}
}, 100);

Programmatically set the Shopify context

You may want to set the Shopify context programmatically. This is useful when using our chat widget in a headless Shopify. To do so, we expose the setShopifyContext method that allows you to provide the Shopify permanent domain (that contains `.myshopify.com`), the user Shopify email, and the Shopify customer id. Note that the Shopify permanent domain parameter is required for this function, while the other parameters are nullable. - please note that this variable is only trustworthy after the Chat initialization.

var gorgiasChatInterval = window.setInterval(function() {
if (window.GorgiasChat && GorgiasChat.hasOwnProperty("setShopifyContext")) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.
GorgiasChat.setShopifyContext('shopname.myshopify.com', 'shopifyuser@email.com', 123456789);
}
}, 100);

// if user email and customer id not known
var gorgiasChatInterval = window.setInterval(function() {
if (window.GorgiasChat && GorgiasChat.hasOwnProperty("setShopifyContext")) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.
GorgiasChat.setShopifyContext('shopname.myshopify.com');
}
}, 100);

Programmatically capture the Shopify cart

You may want to link a specific cart with the current chat user. To do so, we expose the `captureShopifyCart` method that allows you to provide the Shopify Cart of the Shopify user currently using the chat. The cart details will be displayed in the sidebar of the ticket on the helpdesk application.

var gorgiasChatInterval = window.setInterval(function() {
if (window.GorgiasChat && GorgiasChat.hasOwnProperty("captureShopifyCart")) {
window.clearInterval(gorgiasChatInterval); // this line breaks out of the loop - make sure it's not deleted.
var response = await fetch('/cart.json');
var cart = response.json();
GorgiasChat.captureShopifyCart(cart);
}
}, 100);


How did we do?


Powered by HelpDocs (opens in a new tab)