Advanced chat customizationUpdated 2 hours ago
If you would like to further customize the chat widget, you can follow the instructions below. However, you may first want to check out this guide on how to set up some basic chat customization.
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 Shopify Liquid if you use Shopify.
For any non-script codes, like the one that changes the z-index in the style, you have to go into their 'Theme Manager → Edit Theme' and find the home.html file.
We recommend for these steps to be performed by someone with a technical background as you're experimenting with the chat set-up.
How to find and access theme.liquid files
Every code snippet used to customize the widget should be placed just below the chat installation script between the ‘<body>’ and ‘</body>’ tag. To find the script and place any custom code, you will need to find your Shopify store's theme.liquid files. Here’s how to get there:
- From the Shopify admin, go to Online Store → Themes.
- Click Actions → Edit code.
Detailed instructions in Shopify’s FAQs here.

Additional instructions for Shopify
- Navigate to your Shopify home screen.
- Click on 'Online Store' on the left.
- Select Pages → The page where you want to add the link (Ex. Contact Us page).
- Add the code:
- Copy the code above (choose the code depending on what you want to do).
- In the text box under Content, click on the '<>' icon (it says 'Show HTML' on hover). This will switch your view from text only to HTML view.
- Paste the code.
- Edit the text (optional):
- Go back to the original view by clicking on the '<>' icon again.
- By default, it will say, 'Start a chat with our team!', but you may customize this text if you want to.
- Click 'Save'.
Using the Gorgias Chat JavaScript API
The Gorgias Chat Javascript API helps you configure and customize your chat in some pretty advanced ways. The Chat API is available in Javascript from the GorgiasChat
object as a member of the Window Object.
Before you call some of the methods, you need to make sure the chat is fully initialized, this is done with the GorgiasChat.init()
method (note that some of the scripts need to be implemented without the Gorgias wrapper):
New Method (recommended)
1var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});23initGorgiasChatPromise.then(async () => {4 // custom code5})67
Old Method (depreciated)
1// Make sure that Gorgias Chat code snippet is called before your advanced code:2<script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=XXX"></script>345// Advanced code:6<script>7GorgiasChat.init().then(function() {8 // Use GorgiasChat API here, now that the chat is fully initialized.9})10</script>
GorgiasChat
without the init().then(...)
callback in an HTML script tag <script></script>
because your script code might run before the chat is downloaded and initialized.Advanced Personalization
Disable auto open
Except when using a mobile device, the chat window will auto open for returning customers if they left the chat window opened and their last visit was not more than 4 days ago. You can prevent this using the following method:
1<script>2 window.GORGIASCHAT_DISABLE_AUTO_OPEN = true3</script>
*note: unlike the rest of the Gorgias chat API scripts, the one above should be implemented WITHOUT the gorgiaschat.init wrapper below due to the difference in logic on our back end.
Here's how the wrapper looks for reference, and should be excluded from the above script:
1<script>2GorgiasChat.init().then(function() {34})5</script>67
Disable automatic font color change
The chat will adjust font and icon color based on your configuration for "main" and "conversation" colors to improve accessibility and readability. Font and icon color will be dark over light background colors, and light over dark background colors based on contrast ratio. You can prevent this by using the following method:
1<script>2 window.GORGIASCHAT_DISABLE_CONTRAST_COLOR = true3</script>
*note: unlike the rest of the Gorgias chat API scripts, the one above should be implemented WITHOUT the gorgiaschat.init wrapper below due to the difference in logic on our back end.
Here's how the wrapper looks for reference, and should be excluded from the above script:
1<script>2GorgiasChat.init().then(function() {34})5</script>67
Remove 'Powered by Gorgias' branding
You can remove the 'Powered by Gorgias' branding using the following method:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(async () => {5 GorgiasChat.hidePoweredBy(true)6})7</script>89
The branding is displayed on both the chat and the chat campaigns.
Create an "open chat" link on your page
If you want to add a link on your page to open the chat when clicked, use the code below:
1<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>
Display the chat widget after some time spent on the website
To only display the chat after a certain amount of time, use the following method:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(async function() {5 var chatElem = document.getElementById("gorgias-chat-container")6 chatElem.style.display = "none";78 function sleep(seconds) {9 return new Promise(resolve => setTimeout(resolve, seconds * 1000));10 }1112 await sleep(5) // CHANGE THIS VALUE TO THE NUMBER OF SECONDS TO WAIT BEFORE SHOWING THE CHAT BUBBLE13 chatElem.style.display = "";14})15</script>
Display the chat widget on certain store pages only
If you'd prefer to have your chat widget shown on certain pages on your website only, then you can achieve this by adding this code snippet:
1```2{% if request.path != '/collections/all' %}3 <script type="text/javascript" id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=8"></script>4{% endif %}5```
For further information you can also follow this setup doc from Shopify on how to do this as well.
Change the position of chat on different pages of your store
12<style>3 #chat-button {4 right: 0px !important;5 top: 0px !important;6 }78 #chat-window {9 right: 0px !important;10 top: 0px !important;11 }1213 #chat-campaigns {14 right: 0px !important;15 top: 0px !important;16 }17</style>1819
Remove the chat outside business hours
The following method can be used to hide the chat outside your business hours:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.hideOutsideBusinessHours(true) // true to hide when outside of business hours, false to show.6 })7</script>
Set custom business hours
The following method can be used to set custom business hours for your chat:
1<script>2 var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34 initGorgiasChatPromise.then(function () {5 // Edit business hours on the go, if `Hide chat outside of business hours` is enabled, the chat will automatically appear or disappear.6 GorgiasChat.setCustomBusinessHours({7 // Using a timezone from https://en.wikipedia.org/wiki/List_of_tz_database_time_zones8 // Day 1 represents Monday, Day 7 represents Sunday9 timezone: "Australia/Sydney",10 businessHours: [11 { days: [1, 2, 3], fromTime: "08:15", toTime: "17:50" },12 { days: [4, 5], fromTime: "08:15", toTime: "12:00" }13 ]14 })15 });16</script>
Have the chat widget automatically displayed in the language of the store
First, you would need to remove the existing Gorgias chat snippet, and instead insert the following code:
1{% if shop_locale.iso_code == "en-US" %}2 <script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=123123"></script>3{% elsif shop_locale.iso_code == "fr-CA" %}4 <script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=456456"></script>5{% else %}6 <script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=789789"></script>7{% endif %}
Under each {% %} block you will need to add correct <script> tag, we placed random numbers, but if you're doing this on your end, you would need to navigate to your Chat widget in Gorgias Settings>Chat>Installation, and then choose: “custom installation” and find correct line.
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.
You can change the following hardcoded text values on the chat widget using the code below:
- Online and offline introduction text
- Message input placeholder
- Email prompt placeholder
- Email prompt input label
- Email prompt online trigger text
- Email prompt online thanks text
- Email prompt offline trigger text
- Email prompt offline thanks text
- Email prompt required email placeholder
- Email prompt required message placeholder
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 var chatDict = {6 actionPostbackError:7 'An error occurred while processing your action. Please try again.',8 backLabelBackAt: 'Back online at {time}',9 backLabelBackInAMinute: 'Back in 1 minute',10 backLabelBackInAnHour: 'Back in 1 hour',11 backLabelBackInDays: 'Back in {value} days',12 backLabelBackInHours: 'Back in {value} hours',13 backLabelBackInMinutes: 'Back in {value} minutes',14 backLabelBackOn: 'Back on {weekday}',15 backLabelBackTomorrow: 'Back soon',16 campaignClickToReply: 'Click to reply',17 cannotUploadMoreFiles:18 'Cannot upload more than {maxFilesPerUpload} files at the same time.',19 characters: 'characters',20 clickToRetry: 'Click to retry.',21 contactFormAskAdditionalMessage:22 'Would you like to add any more information?',23 contactFormAskEmail: 'How can we contact you?',24 contactFormAskMessage:25 'Got it! Share any additional details to help us assist you.',26 contactFormAskSubject: 'What can we help you with?',27 contactFormAskSubjectOther: 'Please type the subject:',28 contactFormEndingMessage: "Thanks for your message, we'll email you soon.",29 contactFormEndingMessageWithHelpCenter:30 "Thanks for your message, we'll email you soon. In the meantime, visit our Help Center!",31 contactFormIntro: "Leave a message and we'll email you once we're online.",32 contactFormSSPUnsuccessfulAskAdditionalMessage:33 'Sorry to hear that! Share any additional details to help us assist you.',34 conversationTimestampHeaderFormat: 'MMMM D',35 emailCaptureInputLabel: 'Get notified by email',36 emailCaptureOfflineThanksText:37 "Thanks {email}! We'll get back to you shortly.",38 emailCaptureOfflineTriggerText:39 "We're away, leave us your email and we'll respond shortly.",40 emailCaptureOnlineThanksText:41 "Thanks! We'll email you at {email} if you leave.",42 emailCaptureOnlineTriggerText:43 'Leave us your email and we will reply soon.',44 emailCaptureOnlineTriggerTextShortly:45 "Leave us your email and we'll get back to you shortly.",46 emailCapturePlaceholder: '[email protected]',47 emailCaptureRequiredEmailPlaceholder: 'Leave your email',48 emailCaptureRequiredMessagePlaceholder: 'Write your message',49 emailCaptureThanksText:50 "Thanks for reaching out! You'll get replies here and in your email.",51 emailCaptureTriggerBackOnlineAt: "We'll be back online at {time}",52 emailCaptureTriggerBackOnlineOn: "We'll be back online on {weekday}",53 emailCaptureTriggerTextBase:54 "Leave us your email and we'll get back to you.",55 emailCaptureTriggerTypicalReplyDay: 'We typically reply in a day.',56 emailCaptureTriggerTypicalReplyHours: 'We typically reply in a few hours.',57 emailCaptureTriggerTypicalReplyMinutes:58 'We typically reply in a few minutes.',59 fetchHistory: 'Load more',60 fetchingHistory: 'Retrieving history...',61 fileTooBig: 'File should be smaller than {maxFileSize} MB',62 getRepliesByEmail: 'Get replies by email',63 headerText: 'Gorgias Team',64 howCanWeHelpToday: 'How can we help you today?',65 inputPlaceholder: 'Type a message...',66 introductionText: 'How can we help?',67 invalidFileError:68 'Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).',69 leaveAMessage: 'Leave A Message',70 leaveAnotherMessage: 'Leave Another Message',71 messageDelivered: 'Delivered',72 messageError:73 'An error occurred while sending your message. Please try again.',74 messageIndicatorTitlePlural: '({count}) New messages',75 messageIndicatorTitleSingular: '({count}) New message',76 messageNotDelivered: 'Message not delivered. ',77 messageRelativeTimeDay: '{value}d ago',78 messageRelativeTimeHour: '{value}h ago',79 messageRelativeTimeJustNow: 'Just now',80 messageRelativeTimeMinute: '{value}m ago',81 messageSending: 'Sending...',82 messageTimestampFormat: 'h:mm A',83 noAttachmentToSend: 'No attachment to send',84 offlineIntroductionText: "We'll be back soon",85 poweredBy: 'Powered by',86 poweredByGorgias: 'Powered by Gorgias',87 productInformation: 'Product information',88 productQuestionShort: 'Product Question',89 requireEmailCaptureIntro:90 "Hi, hope you're doing well! Leave us your email so we can get back to you.",91 send: 'Send',92 shopClosed: '{shopName} is now closed. Agents might not be available.',93 shopClosingInAMinute: '{shopName} is closing in 1 minute.',94 shopClosingInLessThanAMinute:95 '{shopName} is closing in less than 1 minute.',96 shopClosingSoon: '{shopName} is closing in {minutes} minutes.',97 subject: 'Subject',98 tapToRetry: 'Message not delivered. Tap to retry.',99 thanksForReachingOut: 'Thanks for reaching out!',100 thatsAll: "That's all",101 unsupportedActionType: 'Unsupported action type.',102 unsupportedMessageType: 'Unsupported message type.',103 usualReplyTimeDay: 'Typically replies within a day',104 usualReplyTimeHours: 'Typically replies in a few hours',105 usualReplyTimeMinutes: 'Typically replies in a few minutes',106 waitForAnAgent: 'Wait for an agent',107 waitTimeAgentsAreBusy:108 'Thanks for reaching out! Our agents are currently busy. Your wait time is greater than 15 minutes.',109 waitTimeLongEmailCaptured:110 "Thank you for your patience. We'll get back to you as soon as agents are available",111 waitTimeLongHeader: 'Wait time is longer than usual',112 waitTimeLongNoEmail:113 "Thank you for your patience. Leave us your email and we'll get back to you as soon as agents are available.",114 waitTimeMediumEmailCaptured:115 'Thanks for reaching out! An agent will get back to you in about {waitTime} minutes.',116 waitTimeMediumHeader: "We'll reply in a few moments",117 waitTimeMediumNoEmail:118 'Thanks for reaching out! Leave us your email and an agent will get back to you in about {waitTime} minutes.',119 waitTimeShortEmailCaptured:120 'Thanks for reaching out! An agent will get back to you soon.',121 waitTimeShortHeader: "We'll be right there!",122 waitTimeShortNoEmail:123 'Thanks for reaching out! Leave us your email and an agent will get back to you soon.',124}125126 window.GORGIAS_CHAT_TEXTS = chatDict127 GorgiasChat.updateTexts(chatDict)128})129</script>
If you have enabled the Self-service feature on the chat, you can use the following script, that allows adjusting both the Chat and Self-service wordings :
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 var chatDict = {6 clickToRetry: "Click to retry.",7 contactFormAskAdditionalMessage: "Would you like to add any more information?",8 contactFormAskEmail: "How can we contact you?",9 contactFormAskMessage: "Got it! Share any additional details to help us assist you.",10 contactFormSSPUnsuccessfulAskAdditionalMessage: "Sorry to hear that! Share any additional details to help us assist you.",11 contactFormAskSubject: "What can we help you with?",12 contactFormAskSubjectOther: "Please type the subject:",13 contactFormEndingMessage: "Thanks for your message, we'll email you soon.",14 contactFormEndingMessageWithHelpCenter: "Thanks for your message, we'll email you soon. In the meantime, visit our Help Center!",15 contactFormIntro: "Leave a message and we'll email you once we're online.",16 conversationTimestampHeaderFormat: "MMMM D",17 actionPostbackError: "An error occurred while processing your action. Please try again.",18 fetchHistory: "Load more",19 fetchingHistory: "Retrieving history...",20 invalidFileError: "Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).",21 leaveAMessage: "Leave A Message",22 leaveAnotherMessage: "Leave Another Message",23 messageError: "An error occurred while sending your message. Please try again.",24 messageIndicatorTitlePlural: "({count}) New messages",25 messageIndicatorTitleSingular: "({count}) New message",26 messageNotDelivered: "Message not delivered. ",27 messageRelativeTimeDay: "{value}d ago",28 messageRelativeTimeHour: "{value}h ago",29 messageRelativeTimeJustNow: "Just now",30 messageRelativeTimeMinute: "{value}m ago",31 messageTimestampFormat: "h:mm A",32 messageSending: "Sending...",33 messageDelivered: "Delivered",34 tapToRetry: "Message not delivered. Tap to retry.",35 unsupportedMessageType: "Unsupported message type.",36 inputPlaceholder: "Type a message...",37 emailCapturePlaceholder: "[email protected]",38 emailCaptureInputLabel: "Get notified by email",39 emailCaptureOnlineTriggerText: "Leave us your email and we will reply soon.",40 emailCaptureOnlineThanksText: "Thanks! We'll email you at {email} if you leave.",41 emailCaptureOfflineTriggerText: "We're away, leave us your email and we'll respond shortly.",42 emailCaptureOfflineThanksText: "Thanks {email}! We'll get back to you shortly.",43 emailCaptureRequiredEmailPlaceholder: "Leave your email",44 emailCaptureRequiredMessagePlaceholder: "Write your message",45 backLabelBackInAMinute: "Back in 1 minute",46 backLabelBackInMinutes: "Back in {value} minutes",47 backLabelBackInAnHour: "Back in 1 hour",48 backLabelBackInHours: "Back in {value} hours",49 backLabelBackInDays: "Back in {value} days",50 backLabelBackTomorrow: "Back soon",51 campaignClickToReply: "Click to reply",52 characters: "characters",53 poweredBy: "Powered by",54 productInformation: "Product information",55 productQuestionShort: "Product Question",56 shopClosingSoon: "{shopName} is closing in {minutes} minutes.",57 shopClosingInAMinute: "{shopName} is closing in 1 minute.",58 shopClosingInLessThanAMinute: "{shopName} is closing in less than 1 minute.",59 shopClosed: "{shopName} is now closed. Agents might not be available.",60 send: "Send",61 usualReplyTimeDay: "Typically replies within a day",62 usualReplyTimeHours: "Typically replies in a few hours",63 usualReplyTimeMinutes: "Typically replies in a few minutes",64 backLabelBackAt: "Back online at {time}",65 backLabelBackOn: "Back on {weekday}",66 emailCaptureTriggerTypicalReplyDay: "We typically reply in a day.",67 emailCaptureTriggerTypicalReplyHours: "We typically reply in a few hours.",68 emailCaptureTriggerTypicalReplyMinutes: "We typically reply in a few minutes.",69 emailCaptureTriggerBackOnlineOn: "We'll be back online on {weekday}",70 emailCaptureTriggerBackOnlineAt: "We'll be back online at {time}",71 emailCaptureThanksText: "Thanks for reaching out! You'll get replies here and in your email.",72 emailCaptureTriggerTextBase: "Leave us your email and we'll get back to you.",73 emailCaptureOnlineTriggerTextShortly: "Leave us your email and we'll get back to you shortly.",74 introductionText: "How can we help?",75 offlineIntroductionText: "We'll be back soon",76 subject: "Subject",77 thatsAll: "That's all",78 headerText: "Gorgias Team",79 poweredByGorgias: "Powered by Gorgias",80 unsupportedActionType: "Unsupported action type."81 }8283 var sspDict = {84 applyPromoCode: "Apply promo code",85 april: "Apr",86 articleThatMayHelp: "Here is an article that may help:",87 articleRecommendationInputPlaceholder: "Need more help? Ask us a question!",88 attemptedDelivery: "Attempted delivery",89 august: "Aug",90 backToHome: "Back To Home",91 billingInformation: "Billing information",92 cancel: "Cancel",93 cancelFulfillment: "Cancel fulfillment",94 cancelMessageDescription: "I'd like to cancel the following fulfillment",95 cancelOrder: "Cancel an order",96 cancelOrderShort: "Cancel Order",97 canceled: "Canceled",98 cancelled: "Cancelled",99 cantSignIn: "Can't sign in?",100 changeShippingAddress: "I'd like to change my shipping address",101 checkpointOrderPlaced: "Order placed",102 checkpointInfoReceived: "Info received",103 checkpointInTransit: "In transit",104 checkpointOutForDelivery: "Out for delivery",105 checkpointAttemptFail: "Failed attempt",106 checkpointDelivered: "Delivered",107 checkpointAvailableForPickup: "Available for pickup",108 checkpointException: "Exception",109 checkpointExpired: "Expired",110 checkpointPending: "Pending",111 checkpointException_001: "Exception",112 checkpointException_002: "Customer moved",113 checkpointException_003: "Customer refused delivery",114 checkpointException_004: "Delayed (Customs clearance)",115 checkpointException_005: "Delayed (External factors)",116 checkpointException_006: "Held for payment",117 checkpointException_007: "Incorrect Address",118 checkpointException_008: "Pick up missed",119 checkpointException_009: "Rejected by carrier",120 checkpointException_010: "Returning to sender",121 checkpointException_011: "Returned to sender",122 checkpointException_012: "Shipment damage",123 checkpointException_013: "Shipment lost",124 checkSpamFolder: "If you can't find the verification email, please check your spam and junk folders.",125 codeExpiresIn: "Code expires in",126 codeSentTo: "Code sent to",127 codeWillExpire: "This code will expire in 10 minutes. If you didn't initiate this request, please let our support agents know.",128 confirmed: "Confirmed",129 createdAt: "Created at",130 customerHasNoOrdersEmail: "No orders found for this email",131 customerHasNoOrdersPhone: "No orders found for this phone number",132 damagedInDelivery: "My order was damaged in delivery",133 december: "Dec",134 delivered: "Delivered",135 deliveredAt: "at",136 deliveredOn: "Delivered on",137 deliveredVia: "Shipped via",138 editOrder: "Edit order",139 email: "Email",140 errorFetchingOrders: "An error occurred while fetching your orders",141 estimatedDelivery: "Estimated delivery",142 etaProvidedBy: "ETA provided by",143 expectToBeDeliveredBy: "by",144 failedDelivery: "Failed delivery",145 failedFulfillment: "Failed fulfillment",146 failure: "Failure",147 february: "Feb",148 fillYourEmailToTalkToAnAgent: "Fill your email to talk to an agent",149 findOrder: "Find your order",150 fulfillment: "Fulfillment",151 fulfillmentDetails: "Fulfillment details",152 happyToHelp: "Happy to help, have a great day!",153 hiFirstname: "Hi {{firstName}},",154 howCanIHelp: "How can we help?",155 iHaveTheFollowingIssue: "I have the following Issue:",156 iWouldLikeToCancelTheFollowingOrder: "I'd like to cancel the following order",157 iWouldLikeToReturnTheFollowingItems: "I'd like to return the following items",158 inTransit: "In transit",159 inTransitVia: "In-transit via",160 incorrectOrder: "I did not receive the correct order",161 invalidCode: "Invalid code",162 invalidPhoneNumber: "Invalid phone number",163 itemNames: "Item names",164 itemsRequestedForReturn: "Items requested for return",165 january: "Jan",166 july: "Jul",167 june: "June",168 labelPrinted: "Label printed",169 labelPurchased: "Label purchased",170 lastUpdated: "Last updated",171 learnMore: "Learn more",172 lostOrderDetails: "Lost your order details? Talk to an agent",173 manageYourOrders: "Manage your orders",174 march: "Mar",175 maxVerificationAttemptsReached: "Maximum verification attempts reached",176 may: "May",177 needHelp: "Need more help?",178 noCustomerAssociatedEmail: "No customer associated with this email",179 noCustomerAssociatedPhone: "No customer associated with this phone number",180 noINeedMoreHelp: "No, I need more help",181 november: "Nov",182 october: "Oct",183 of: "of",184 oneItemSelected: "1 item selected",185 order: "Order",186 orderCreated: "Order Created",187 orderNotFound: "We have no record of that order number and email combination. Please try again or ",188 orderNumber: "Order number",189 orderPlaced: "Order placed",190 other: "Other",191 outForDelivery: "Out for delivery",192 outForDeliveryVia: "Out for delivery via",193 partiallyRefunded: "Partially refunded",194 pastDeliveryDate: "I'm past my expected delivery date",195 payment: "Payment",196 pendingDelivery: "Pending delivery",197 pleaseRefreshPageToUseChat: "Please refresh your page to continue using the chat.",198 pleaseUseVerificationCodeToLogIn: "Please use this verification code to complete your log-in:",199 previousConversation: "Go to previous conversation",200 processing: "Processing",201 processingFulfillment: "Processing fulfillment",202 provideEmailAndOrderNumber: "You must provide an email and an order number",203 quantityToReturn: "Quantity to return",204 quickAnswers: "Quick answers",205 readyForPickup: "Ready for pickup",206 reasonCancelOrder: "I'd like to cancel my order",207 reasonCancelSubscription: "I'd like to cancel my subscription",208 reasonChangeDeliveryDate: "I'd like to change the delivery date",209 reasonChangeShippingAddress: "I'd like to change my shipping address",210 reasonDidNotReceiveRefund: "I didn't get my refund",211 reasonDiscountNotWorking: "My discount code is not working",212 reasonEditOrder: "I'd like to edit my order",213 reasonEditSubscription: "I'd like to edit my subscription",214 reasonExchangeRequest: "I'd like to exchange items in my order",215 reasonForgotToUseDiscount: "I forgot to apply my discount code",216 reasonIncorrectItems: "The items are different from what I ordered",217 reasonItemsMissing: "Some items are missing from my order",218 reasonNotHappy: "I'm not happy with the product I received 👎",219 reasonOrderDamaged: "My order was damaged in delivery",220 reasonOrderDefective: "The items in my order are defective",221 reasonOrderStillNotShipped: "My order should have shipped by now",222 reasonOrderStuckInTransit: "My order has been stuck in transit",223 reasonOther: "Other",224 reasonPastExpectedDeliveryDate: "I'm past my expected delivery date",225 reasonReorderItems: "I'd like to reorder some items",226 reasonReplaceItemsRequest: "I'd like to replace items in my order",227 reasonRequestDiscount: "I'd like a discount code",228 reasonRequestRefund: "I'd like to get a refund for this order",229 reasonReturnProduct: "I'd like to return a product",230 reasonVeryHappy: "I'm very happy with the product I received 👍",231 reasonWhereIsMyOrder: "Where is my order?",232 refunded: "Refunded",233 reportAnIssueWithOrder: "Report an issue with an order",234 reportIssue: "Report issue",235 reportIssueShort: "Report Issue",236 requestCancellation: "Request Cancellation",237 requestReturn: "Request Return",238 resendCode: "Resend code",239 return: "Return",240 returnItems: "Return items",241 returnOrder: "Return an order",242 returnOrderShort: "Return Order",243 see1MoreItem: "1 more item",244 see1MoreOrder: "See 1 more order",245 seeArticles: "See Articles",246 seeMoreItems: "{moreItemsCount} more items",247 seeMoreOrders: "See {nextPageOrderCount} more orders",248 seeOrders: "See your orders",249 selectAll: "Select all",250 sendUsAMessage: "Send us a message",251 sendCode: "Send code",252 sent: "Sent",253 september: "Sept",254 severalItemsSelected: "{itemsSelectedCount} items selected",255 shipmentBeingDelivered: "Order shipment is being delivered to its final destination.",256 shipping: "Shipping",257 shippingAddress: "Shipping address",258 shippingInformation: "Shipping information",259 showLessItems: "Show less",260 signIn: "Sign in",261 sincerely: "Sincerely,",262 sms: "SMS",263 sorryToHearThatEmailRequired: "Sorry to hear that. Leave us your email and we'll get back to you.",264 sorryToHearThatEmailNotRequired: "Sorry to hear that! Someone will be with you soon.",265 sorryToHearThatOfflineEmailCaptured: "Sorry to hear that, we'll get back to you by email.",266 sorryToHearThatOnlineEmailCaptured: "I'm sorry to hear that. An agent will be with you in a few minutes.",267 startConversation: "Start conversation",268 stuckInTransit: "My order has been stuck in transit for several days",269 subtotal: "Subtotal (Inc. tax)",270 summary: "Summary",271 supportTeam: "The {{shopFriendlyName}} support team",272 talkToLiveAgent: "talk to a live agent",273 thanksOurTeamWillRespond: "Thanks, our team will respond shortly.",274 total: "Total",275 track: "Track",276 trackOrder: "Track an order",277 trackOrderShort: "Track Order",278 trackingNumber: "Tracking number",279 trackingNumberPrefix: "Tracking no.",280 trackingUrl: "Tracking Url",281 trySigningInWithOrderNumber: "Try signing in with order number",282 unavailable: "Unavailable",283 unfulfilled: "Unfulfilled",284 verificationCodeField: "6-digit code",285 wasThisRelevant: "Was this relevant?",286 whatIsWrongWithOrder: "What is wrong with your order?",287 yesThankYou: "Yes, thank you",288 yourEmail: "Your email",289 yourOrders: "Your orders",290 yourPhoneNumber: "Your phone number",291 youWillGetRepliesHereAndByEmail: "Thanks! You'll get replies here and by email.",292 youWillGetRepliesByEmail: "Thanks! You'll get replies by email.",293 errorSendingReportIssue: "Something went wrong while sending the report issue."294 }295296 window.GORGIAS_CHAT_TEXTS = chatDict297 GorgiasChat.updateTexts(chatDict)298 GorgiasChat.updateSSPTexts(sspDict)299})300</script>
Instructions for Shopify:
- Go to your Shopify's theme.liquid to edit the code.
- Navigate to your Shopify home screen.
- Click on 'Online Store' on the left.
- Select Themes → Actions → Edit code.
- Under Layout, choose theme.liquid.
- Add the code:
- Copy the code above.
- Paste the code at the last line of the text code box.
- Edit the text of the item that you want to change.
- For example, you want to edit the message input placeholder ("Type a message...").
- If you want to change this, erase the text between the quotation marks.
- For example, you want to edit the message input placeholder ("Type a message...").
- Click 'Save'.
Chat Dynamic wait time
1 "waitForAnAgent": "Wait for an agent",2 "waitTimeAgentsAreBusy": "Thanks for reaching out! Our agents are currently busy. Your wait time is greater than 15 minutes.",3 "waitTimeLongEmailCaptured": "Thank you for your patience. We'll get back to you as soon as agents are available",4 "waitTimeLongHeader": "Wait time is longer than usual",5 "waitTimeLongNoEmail": "Thank you for your patience. Leave us your email and we'll get back to you as soon as agents are available.",6 "waitTimeMediumEmailCaptured": "Thanks for reaching out! An agent will get back to you in about {waitTime} minutes.",7 "waitTimeMediumHeader": "We'll reply in a few moments",8 "waitTimeMediumNoEmail": "Thanks for reaching out! Leave us your email and an agent will get back to you in about {waitTime} minutes.",9 "waitTimeShortEmailCaptured": "Thanks for reaching out! An agent will get back to you soon.",10 "waitTimeShortHeader": "We'll be right there!",11 "waitTimeShortNoEmail": "Thanks for reaching out! Leave us your email and an agent will get back to you soon."
Display currently used text values
If you wish to display the current text values, run the following in the console:
1window.GorgiasChat.printLabelDictionary()
Toggle the display of translation keys/text values in the chat
If you wish to display the translation keys in the chat instead of the text values, run the following in the console:
1window.GorgiasChat.showTranslationKeys(true)
In a similar fashion, you can go back to text values with the following code:
1window.GorgiasChat.showTranslationKeys(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, chat window, and chat campaigns.
Add the following script to your web page where the chat is installed and modify the lines xxxStyle.textContent = '...'
, replacing the content with your own CSS rules:
1// Use this script to customize the chat button.2 <script>3 var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});45 initGorgiasChatPromise.then(function () {67 var timer = setInterval(function () {8 var chatButtonHead = document.querySelector('#gorgias-chat-container')?.querySelector('#chat-button')?.contentWindow.document.querySelector('head');9 if (!chatButtonHead || ![...chatButtonHead?.children].some(x => x.getAttribute("data-emotion"))) {10 return;11 }12 clearInterval(timer);1314 var buttonStyle = document.createElement('style');15 buttonStyle.textContent = '#gorgias-chat-messenger-button {background-color: orange; transition: background-color 200ms ease;}'; // the custom CSS for the chat button16 chatButtonHead.appendChild(buttonStyle);17 }, 50);18 })19 </script>202122// Use this script to customize the chat window.23 <script>24 var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});2526 initGorgiasChatPromise.then(function () {27 GorgiasChat.on('widget:opened', function () {28 var timer = setInterval(function () {29 var chatWindowHead = document.querySelector('#gorgias-chat-container')?.querySelector('#chat-window')?.contentWindow.document.querySelector('head');30 if (![...chatWindowHead?.children].some(x => x.getAttribute("data-emotion"))) {31 return;32 }33 clearInterval(timer);3435 var chatStyle = document.createElement('style');36 chatStyle.textContent = '.message-window-iframe-1g7otri {box-shadow: none; background-color: lawngreen}'; // window header green37 chatWindowHead.appendChild(chatStyle);38 }, 50);39 })4041 })42 </script>
Replace the chat widget button
You have the ability to replace our chat widget button with your own by providing some custom code. The following custom script would replace the original widget button with a custom button element.
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function () {5 var timer = setInterval(function () {6 var chatButtonHead = document.querySelector('#gorgias-chat-container')?.querySelector('#chat-button')?.contentWindow.document.querySelector('head');7 if (!chatButtonHead?.children.length) {8 return;9 }10 clearInterval(timer);1112 var chatButtonIframe = document.querySelector('#chat-button');13 chatButtonIframe.style = "display:none;"1415 // replace our button with your own var myButton = document.createElement('button');16 myButton.style = `17 position: fixed;18 right: 100px; bottom: 10px;19 z-index: 2147483000;20 width: 50px;21 height: 50px;22 border-radius: 10px;23 background-color: blue;24 `2526 // onClick, behave like a chat opener27 myButton.onclick = function () {28 if (GorgiasChat.isOpen()) {29 GorgiasChat.close();30 } else {31 GorgiasChat.open();32 }33 }34 document.body.appendChild(myButton);35 }, 50);36});37</script>
Chat interactions with JavaScript
Configuring the chat with URL query parameters
You may configure the chat behavior with URL query parameters to share such links with your customers.
Let's assume that your store's URL is www.my-store.com
:
Opening the chat automatically
You can make the chat open automatically on page load by adding the gs_open_chat
parameter to your URL (notice the gs_
which stands for 'gorgias'). The resulting store URL is now www.my-store.com?gs_open_chat
.
Setting the default chat page
You can set up a chat page that will be showing by default for your customers with the query parameter gs_chat_page
. The value can be either conversation
(for the chat messages page) or homepage
(for the self-service page, to fall back to the chat messages page if self-service is disabled).
For instance, www.my-store.com?gs_chat_page=conversation
sets the conversation page as the default one. www.my-store.com?gs_chat_page=homepage
sets the self-service page as the default one.
Pre-filling the user message
You can direct your customers to a URL where the chat will have a pre-filled message by using the query parameter gs_chat_message=mymessage
where 'mymessage' is your custom message. Note that the message must be URL encoded. For example, the message 'I want information on product...' must be URL-encoded as I%20want%20information%20on%20product...
.
The resulting URL to your store would be www.my-store.com?gs_chat_message=I%20want%20information%20on%20product...
Using more than one parameter at the same time
Let's say that you want to open the chat automatically, and also set the default page as conversation, and pre-fill the user message with 'Hello'. You can combine all the parameters together in a single URL by separating them with an '&'.
For instance: www.my-store.com?gs_open_chat&gs_chat_page=conversation&gs_chat_message=Hello
You are now ready to share these links with your users!
Pre-fill the user message
If you want to pre-fill the user message input field, you can use the following method with a string parameter:
1<script>2GorgiasChat.init().then(function() {3 GorgiasChat.setCurrentInput('Hello !')4})5</script>
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:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.isOpen() // Will return true or false.6})7</script>
Check whether the current time is in business hours
You may use the following method to determine whether the chat business hours (as defined in the helpdesk) are displayed correctly. Please just keep in mind that this variable is only trustworthy after chat initialization:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.isBusinessHours() // Will return true or false.6})7</script>
Disable the Self-service Portal
If you have the self-service features enabled, but you wish to hide self-service on certain pages, it is possible to add the following script to disable the Self-service Portal:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.disableSSP()6})7</script>
Disable or Enable the live chat mode
Live chat lets customers start live conversations with agents. When disabled, customers can still interact with self-service features and fill out the contact form.
You can also edit the Live chat preference from code with the following:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.enableOfflineMode() // Live chat OFF6 GorgiasChat.disableOfflineMode() // Live chat ON7})8</script>
Set the current page of the chat
You can change the current page of the chat with this method:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 // To show the conversation page.6 GorgiasChat.setPage('conversation')78 // To show the self-service screen.9 GorgiasChat.setPage('homepage') // Note that the conversation page is showed if the self-service is disabled.10})11</script>
Subscribe to chat events
Sometimes it's useful to do something specific when the chat widget is open or closed. You can use the example below to do that.
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.on('EVENT_NAME', function(data) {6 // your code should go here7 })8})9</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.
Programmatically send a message
To send a message from the user via the chat programmatically, you may use this method with a string parameter:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.sendMessage('the message')6})7</script>
GorgiasChat.open()
.Programmatically capture an email
You may want to set up the shopper's email programmatically. To do so, we exposed the captureUserEmail
method that allows you to change the user email associated to the current chat conversation.
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.captureUserEmail('[email protected]');6})7</script>
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.
1<script>2async function getCart(url = '/cart.json') {3 const response = await fetch(url, {4 method: 'GET',5 });6 return response.json();7}89var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});1011initGorgiasChatPromise.then(function() {12 getCart().then(function(cart) {13 GorgiasChat.captureShopifyCart(cart);14 });15})16</script>
Additional features
Disable Segment
To disable Segment (a script used to gather analytics) use the following script:
1<script>2var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});34initGorgiasChatPromise.then(function() {5 GorgiasChat.disableSegment()6})7</script>
Remove the chat based on country code
If you only work with certain countries you might want to only handle chat messages coming from those countries. The code below hides the chat for ALL countries except United States (US) and Mexico (MX):
1<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>2<script>3// set your ipstack API key4var ipstackAPIKey = 'YOUR_API_KEY'5// set your country code whitelist6var countryCodeWhiteList = ['US', 'MX']7// set this to false if you only have a free tier account for ipstack8var useHttps = true910var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});1112function removeGorgiasChat(countryCode) {13 initGorgiasChatPromise.then(function() {14 var container = document.querySelector('#gorgias-chat-container');15 if (container && !countryCodeWhiteList.includes(countryCode)) {16 container.remove()17 }18 })19}2021var countryCode = window.localStorage.getItem('countryCode')22if (!countryCode) {23 protocol = useHttps ? 'https' : 'http'24 $.ajax({25 url: protocol + '://api.ipstack.com/check?access_key=' + ipstackAPIKey + '&fields=country_code',26 dataType: 'jsonp',27 success: function (json) {28 if (json && json.country_code) {29 countryCode = json.country_code30 } else {31 countryCode = 'unknown'32 }33 window.localStorage.setItem('countryCode', countryCode)34 removeGorgiasChat(countryCode)35 },36 error: function (request, status, error) {37 console.error(request.responseText);38 window.localStorage.setItem('countryCode', 'unknown')39 removeGorgiasChat('unknown')40 }41 })42} else {43 removeGorgiasChat(countryCode)44}45</script>
Instructions for Shopify:
- Go to your Shopify store's theme.liquidto edit the code.
- Navigate to your Shopify home screen.
- Click on 'Online Store' on the left.
- Select Themes → Actions → Edit code.
- Under Layout, choose theme.liquid.
- Add the code:
- Copy the code above and paste it on the code text box.
- Enter your ipstack API key where the code says
'YOUR_API_KEY'
. - Enter the country code/s where you only want to display the chat widget where it says
['US', 'MX']
. - In the part where it says 'var useHttps = true', change it from 'true' to 'false' if you're using a free account on ipstack. Otherwise, feel free to just leave it be.
- Click on 'Save'. The chat won't be available to anyone except for shoppers from the countries you entered.
Remove the chat only on one page of the store
1<script>2 var pagesToHide = [3 'INSERT_PAGE_URL_ONE',4 'INSERT_PAGE_URL_TWO',5 ]6 var initGorgiasChatPromise = (window.GorgiasChat) ? window.GorgiasChat.init() : new Promise(function (resolve) { window.addEventListener('gorgias-widget-loaded', function () { resolve();})});78 initGorgiasChatPromise.then(function() {9 if (pagesToHide.includes(window.location.href)) {10 GorgiasChat.hideChat(true);11 }12 })13</script>
Install a multilingual chat
In the event that you need to have a multilingual chat widget installed on your store, you can use the following code. Here, we are using French in the example.
1{% if shop.locale == 'fr' %}2<script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=3333">3</script>4{% else %}5‹script id="gorgias-chat-widget-install-v2" src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=3333">6</script>7{% endif %}
Troubleshooting
Uncaught ReferenceError: GorgiasChat is not defined
This console error means that the Gorgias Chat code snippet is either missing in the page, or called after the custom script. Lastly, please verify that you are well using the Gorgias chat bundle loader version 2 by checking that you have gorgias-chat-widget-install-v2
in the script.
The chat is conflicting with other widgets
If your chat widget is conflicting or is hidden behind some other elements on the page, like the accessibility widget, rewards widget, etc., changing the z-index should overlay the chat on top of any other element. To do this, add this code to your site:
1<style>2#gorgias-chat-container iframe#chat-window,3#gorgias-chat-container iframe#chat-campaigns {4 z-index: 2147483647 !important;5}6#gorgias-chat-container iframe#chat-button {7 z-index: 2147483646 !important;8}9</style>
If you wish to hide the Gorgias chat behind other elements on the page, you can use the following code:
1<style>2#gorgias-chat-container iframe#chat-window,3#gorgias-chat-container iframe#chat-campaigns {4 z-index: 99 !important;5}6#gorgias-chat-container iframe#chat-button {7 z-index: 99 !important;8}9</style>1011
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.
Instructions for Shopify:
- Go to your Shopify store's theme.liquid to edit the code.
- Navigate to your Shopify home screen.
- Click on 'Online Store' on the left.
- Select Themes → Actions → Edit Code.
- Under Layout, choose theme.liquid.
- Add the code:
- Copy the code above.
- Paste it on the first line or the last line in the text code box.
- Click 'Save'. The chat widget should not be hidden now.
Hope this helps you master some code and turn your chat widget into a custom-built tool that will get your customer service to the next level! As always, our Support Team is here for you if you have any follow-up questions, so please feel free to reach out via our live chat or email at [email protected]