Gorgias logo
Gorgias logo

All collections

Advanced chat customization

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.


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 that changes the z-index in the style, 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. As such, our support for these types of customization is limited.
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:

  1. From the Shopify admin, go to Online StoreThemes.
  2. Click ActionsEdit code.

Detailed instructions in Shopify’s FAQs here.


Additional instructions for Shopify
  1. Go to your Shopify store's theme.liquid to edit the code.
  2. Navigate to your Shopify home screen.
  3. Click on 'Online Store' on the left.
  4. Select Pages → The page where you want to add the link (Ex. Contact Us page).
  5. Add the code:
    1. Copy the code above (choose the code depending on what you want to do).
    2. 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.
    3. Paste the code.
  6. Edit the text (optional):
    1. Go back to the original view by clicking on the '<>' icon again.
    2. By default, it will say, 'Start a chat with our team!', but you may customize this text if you want to.
  7. 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 any methods, you need to make sure the chat is fully initialized, this is done with the GorgiasChat.init() method:

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>
3
4
5// Advanced code:
6<script>
7GorgiasChat.init().then(function() {
8 // Use GorgiasChat API here, now that the chat is fully initialized.
9})
10</script>


You must never call 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 = true
3</script>


Remove 'Powered by Gorgias' branding

You can remove the 'Powered by Gorgias' branding using the following method:

1<script>
2 GorgiasChat.init().then(function() {
3 GorgiasChat.hidePoweredBy(true)
4 })
5</script>


The branding is displayed on both the chat and the chat campaigns.


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:

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


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>
2GorgiasChat.init().then(async function() {
3 var chatElem = document.getElementById("gorgias-chat-container")
4 chatElem.style.display = "none";
5
6 function sleep(seconds) {
7 return new Promise(resolve => setTimeout(resolve, seconds * 1000));
8 }
9
10 await sleep(5) // CHANGE THIS VALUE TO THE NUMBER OF SECONDS TO WAIT BEFORE SHOWING THE CHAT BUBBLE
11 chatElem.style.display = "";
12})
13</script>


Remove the chat outside business hours

The following method can be used to hide the chat outside your business hours:

1<script>
2GorgiasChat.init().then(function() {
3 GorgiasChat.hideOutsideBusinessHours(true) // true to hide when outside of business hours, false to show.
4 })
5</script>


Set custom business hours

The following method can be used to set custom business hours for your chat:

1<script>
2 GorgiasChat.init().then(function () {
3 // Edit business hours on the go, if `Hide chat outside of business hours` is enabled, the chat will automatically appear or disappear.
4 GorgiasChat.setCustomBusinessHours({
5 // Using a timezone from https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
6 // Day 1 represents Monday, Day 7 represents Sunday
7 timezone: "Australia/Sydney",
8 businessHours: [
9 { days: [1, 2, 3], fromTime: "08:15", toTime: "17:50" },
10 { days: [4, 5], fromTime: "08:15", toTime: "12:00" }
11 ]
12 })
13 });
14</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.

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 capture placeholder
  • Email capture input label
  • Email capture online trigger text
  • Email capture online thanks text
  • Email capture offline trigger text
  • Email capture offline thanks text
  • Email capture required email placeholder
  • Email capture required message placeholder

1<script>
2GorgiasChat.init().then(function() {
3 var chatDict = {
4 actionPostbackError:
5 'An error occurred while processing your action. Please try again.',
6 backLabelBackAt: 'Back online at {time}',
7 backLabelBackInAMinute: 'Back in 1 minute',
8 backLabelBackInAnHour: 'Back in 1 hour',
9 backLabelBackInDays: 'Back in {value} days',
10 backLabelBackInHours: 'Back in {value} hours',
11 backLabelBackInMinutes: 'Back in {value} minutes',
12 backLabelBackOn: 'Back on {weekday}',
13 backLabelBackTomorrow: 'Back soon',
14 campaignClickToReply: 'Click to reply',
15 cannotUploadMoreFiles:
16 'Cannot upload more than {maxFilesPerUpload} files at the same time.',
17 characters: 'characters',
18 clickToRetry: 'Click to retry.',
19 contactFormAskAdditionalMessage:
20 'Would you like to add any more information?',
21 contactFormAskEmail: 'How can we contact you?',
22 contactFormAskMessage:
23 'Got it! Share any additional details to help us assist you.',
24 contactFormAskSubject: 'What can we help you with?',
25 contactFormAskSubjectOther: 'Please type the subject:',
26 contactFormEndingMessage: "Thanks for your message, we'll email you soon.",
27 contactFormEndingMessageWithHelpCenter:
28 "Thanks for your message, we'll email you soon. In the meantime, visit our Help Center!",
29 contactFormIntro: "Leave a message and we'll email you once we're online.",
30 contactFormSSPUnsuccessfulAskAdditionalMessage:
31 'Sorry to hear that! Share any additional details to help us assist you.',
32 conversationTimestampHeaderFormat: 'MMMM D',
33 emailCaptureInputLabel: 'Get notified by email',
34 emailCaptureOfflineThanksText:
35 "Thanks {email}! We'll get back to you shortly.",
36 emailCaptureOfflineTriggerText:
37 "We're away, leave us your email and we'll respond shortly.",
38 emailCaptureOnlineThanksText:
39 "Thanks! We'll email you at {email} if you leave.",
40 emailCaptureOnlineTriggerText:
41 'Leave us your email and we will reply soon.',
42 emailCaptureOnlineTriggerTextShortly:
43 "Leave us your email and we'll get back to you shortly.",
44 emailCapturePlaceholder: '[email protected]',
45 emailCaptureRequiredEmailPlaceholder: 'Leave your email',
46 emailCaptureRequiredMessagePlaceholder: 'Write your message',
47 emailCaptureThanksText:
48 "Thanks for reaching out! You'll get replies here and in your email.",
49 emailCaptureTriggerBackOnlineAt: "We'll be back online at {time}",
50 emailCaptureTriggerBackOnlineOn: "We'll be back online on {weekday}",
51 emailCaptureTriggerTextBase:
52 "Leave us your email and we'll get back to you.",
53 emailCaptureTriggerTypicalReplyDay: 'We typically reply in a day.',
54 emailCaptureTriggerTypicalReplyHours: 'We typically reply in a few hours.',
55 emailCaptureTriggerTypicalReplyMinutes:
56 'We typically reply in a few minutes.',
57 fetchHistory: 'Load more',
58 fetchingHistory: 'Retrieving history...',
59 fileTooBig: 'File should be smaller than {maxFileSize} MB',
60 getRepliesByEmail: 'Get replies by email',
61 headerText: 'Gorgias Team',
62 howCanWeHelpToday: 'How can we help you today?',
63 inputPlaceholder: 'Type a message...',
64 introductionText: 'How can we help?',
65 invalidFileError:
66 'Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).',
67 leaveAMessage: 'Leave A Message',
68 leaveAnotherMessage: 'Leave Another Message',
69 messageDelivered: 'Delivered',
70 messageError:
71 'An error occurred while sending your message. Please try again.',
72 messageIndicatorTitlePlural: '({count}) New messages',
73 messageIndicatorTitleSingular: '({count}) New message',
74 messageNotDelivered: 'Message not delivered. ',
75 messageRelativeTimeDay: '{value}d ago',
76 messageRelativeTimeHour: '{value}h ago',
77 messageRelativeTimeJustNow: 'Just now',
78 messageRelativeTimeMinute: '{value}m ago',
79 messageSending: 'Sending...',
80 messageTimestampFormat: 'h:mm A',
81 noAttachmentToSend: 'No attachment to send',
82 offlineIntroductionText: "We'll be back soon",
83 poweredBy: 'Powered by',
84 poweredByGorgias: 'Powered by Gorgias',
85 productInformation: 'Product information',
86 productQuestionShort: 'Product Question',
87 requireEmailCaptureIntro:
88 "Hi, hope you're doing well! Leave us your email so we can get back to you.",
89 send: 'Send',
90 shopClosed: '{shopName} is now closed. Agents might not be available.',
91 shopClosingInAMinute: '{shopName} is closing in 1 minute.',
92 shopClosingInLessThanAMinute:
93 '{shopName} is closing in less than 1 minute.',
94 shopClosingSoon: '{shopName} is closing in {minutes} minutes.',
95 subject: 'Subject',
96 tapToRetry: 'Message not delivered. Tap to retry.',
97 thanksForReachingOut: 'Thanks for reaching out!',
98 thatsAll: "That's all",
99 unsupportedActionType: 'Unsupported action type.',
100 unsupportedMessageType: 'Unsupported message type.',
101 usualReplyTimeDay: 'Typically replies within a day',
102 usualReplyTimeHours: 'Typically replies in a few hours',
103 usualReplyTimeMinutes: 'Typically replies in a few minutes',
104 waitForAnAgent: 'Wait for an agent',
105 waitTimeAgentsAreBusy:
106 'Thanks for reaching out! Our agents are currently busy. Your wait time is greater than 15 minutes.',
107 waitTimeLongEmailCaptured:
108 "Thank you for your patience. We'll get back to you as soon as agents are available",
109 waitTimeLongHeader: 'Wait time is longer than usual',
110 waitTimeLongNoEmail:
111 "Thank you for your patience. Leave us your email and we'll get back to you as soon as agents are available.",
112 waitTimeMediumEmailCaptured:
113 'Thanks for reaching out! An agent will get back to you in about {waitTime} minutes.',
114 waitTimeMediumHeader: "We'll reply in a few moments",
115 waitTimeMediumNoEmail:
116 'Thanks for reaching out! Leave us your email and an agent will get back to you in about {waitTime} minutes.',
117 waitTimeShortEmailCaptured:
118 'Thanks for reaching out! An agent will get back to you soon.',
119 waitTimeShortHeader: "We'll be right there!",
120 waitTimeShortNoEmail:
121 'Thanks for reaching out! Leave us your email and an agent will get back to you soon.',
122}
123
124 window.GORGIAS_CHAT_TEXTS = chatDict
125 GorgiasChat.updateTexts(chatDict)
126})
127</script>


You don't need to provide all the available text keys when updating the texts. You can provide us only the relevant custom texts, the rest will use the default text values.

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>
2GorgiasChat.init().then(function() {
3 var chatDict = {
4 clickToRetry: "Click to retry.",
5 contactFormAskAdditionalMessage: "Would you like to add any more information?",
6 contactFormAskEmail: "How can we contact you?",
7 contactFormAskMessage: "Got it! Share any additional details to help us assist you.",
8 contactFormSSPUnsuccessfulAskAdditionalMessage: "Sorry to hear that! Share any additional details to help us assist you.",
9 contactFormAskSubject: "What can we help you with?",
10 contactFormAskSubjectOther: "Please type the subject:",
11 contactFormEndingMessage: "Thanks for your message, we'll email you soon.",
12 contactFormEndingMessageWithHelpCenter: "Thanks for your message, we'll email you soon. In the meantime, visit our Help Center!",
13 contactFormIntro: "Leave a message and we'll email you once we're online.",
14 conversationTimestampHeaderFormat: "MMMM D",
15 actionPostbackError: "An error occurred while processing your action. Please try again.",
16 fetchHistory: "Load more",
17 fetchingHistory: "Retrieving history...",
18 invalidFileError: "Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).",
19 leaveAMessage: "Leave A Message",
20 leaveAnotherMessage: "Leave Another Message",
21 messageError: "An error occurred while sending your message. Please try again.",
22 messageIndicatorTitlePlural: "({count}) New messages",
23 messageIndicatorTitleSingular: "({count}) New message",
24 messageNotDelivered: "Message not delivered. ",
25 messageRelativeTimeDay: "{value}d ago",
26 messageRelativeTimeHour: "{value}h ago",
27 messageRelativeTimeJustNow: "Just now",
28 messageRelativeTimeMinute: "{value}m ago",
29 messageTimestampFormat: "h:mm A",
30 messageSending: "Sending...",
31 messageDelivered: "Delivered",
32 tapToRetry: "Message not delivered. Tap to retry.",
33 unsupportedMessageType: "Unsupported message type.",
34 inputPlaceholder: "Type a message...",
35 emailCapturePlaceholder: "yo[email protected]",
36 emailCaptureInputLabel: "Get notified by email",
37 emailCaptureOnlineTriggerText: "Leave us your email and we will reply soon.",
38 emailCaptureOnlineThanksText: "Thanks! We'll email you at {email} if you leave.",
39 emailCaptureOfflineTriggerText: "We're away, leave us your email and we'll respond shortly.",
40 emailCaptureOfflineThanksText: "Thanks {email}! We'll get back to you shortly.",
41 emailCaptureRequiredEmailPlaceholder: "Leave your email",
42 emailCaptureRequiredMessagePlaceholder: "Write your message",
43 backLabelBackInAMinute: "Back in 1 minute",
44 backLabelBackInMinutes: "Back in {value} minutes",
45 backLabelBackInAnHour: "Back in 1 hour",
46 backLabelBackInHours: "Back in {value} hours",
47 backLabelBackInDays: "Back in {value} days",
48 backLabelBackTomorrow: "Back soon",
49 campaignClickToReply: "Click to reply",
50 characters: "characters",
51 poweredBy: "Powered by",
52 productInformation: "Product information",
53 productQuestionShort: "Product Question",
54 shopClosingSoon: "{shopName} is closing in {minutes} minutes.",
55 shopClosingInAMinute: "{shopName} is closing in 1 minute.",
56 shopClosingInLessThanAMinute: "{shopName} is closing in less than 1 minute.",
57 shopClosed: "{shopName} is now closed. Agents might not be available.",
58 send: "Send",
59 usualReplyTimeDay: "Typically replies within a day",
60 usualReplyTimeHours: "Typically replies in a few hours",
61 usualReplyTimeMinutes: "Typically replies in a few minutes",
62 backLabelBackAt: "Back online at {time}",
63 backLabelBackOn: "Back on {weekday}",
64 emailCaptureTriggerTypicalReplyDay: "We typically reply in a day.",
65 emailCaptureTriggerTypicalReplyHours: "We typically reply in a few hours.",
66 emailCaptureTriggerTypicalReplyMinutes: "We typically reply in a few minutes.",
67 emailCaptureTriggerBackOnlineOn: "We'll be back online on {weekday}",
68 emailCaptureTriggerBackOnlineAt: "We'll be back online at {time}",
69 emailCaptureThanksText: "Thanks for reaching out! You'll get replies here and in your email.",
70 emailCaptureTriggerTextBase: "Leave us your email and we'll get back to you.",
71 emailCaptureOnlineTriggerTextShortly: "Leave us your email and we'll get back to you shortly.",
72 introductionText: "How can we help?",
73 offlineIntroductionText: "We'll be back soon",
74 subject: "Subject",
75 thatsAll: "That's all",
76 headerText: "Gorgias Team",
77 poweredByGorgias: "Powered by Gorgias",
78 unsupportedActionType: "Unsupported action type."
79 }
80
81 var sspDict = {
82 applyPromoCode: "Apply promo code",
83 april: "Apr",
84 articleThatMayHelp: "Here is an article that may help:",
85 articleRecommendationInputPlaceholder: "Need more help? Ask us a question!",
86 attemptedDelivery: "Attempted delivery",
87 august: "Aug",
88 backToHome: "Back To Home",
89 billingInformation: "Billing information",
90 cancel: "Cancel",
91 cancelFulfillment: "Cancel fulfillment",
92 cancelMessageDescription: "I'd like to cancel the following fulfillment",
93 cancelOrder: "Cancel an order",
94 cancelOrderShort: "Cancel Order",
95 canceled: "Canceled",
96 cancelled: "Cancelled",
97 cantSignIn: "Can't sign in?",
98 changeShippingAddress: "I'd like to change my shipping address",
99 checkpointOrderPlaced: "Order placed",
100 checkpointInfoReceived: "Info received",
101 checkpointInTransit: "In transit",
102 checkpointOutForDelivery: "Out for delivery",
103 checkpointAttemptFail: "Failed attempt",
104 checkpointDelivered: "Delivered",
105 checkpointAvailableForPickup: "Available for pickup",
106 checkpointException: "Exception",
107 checkpointExpired: "Expired",
108 checkpointPending: "Pending",
109 checkpointException_001: "Exception",
110 checkpointException_002: "Customer moved",
111 checkpointException_003: "Customer refused delivery",
112 checkpointException_004: "Delayed (Customs clearance)",
113 checkpointException_005: "Delayed (External factors)",
114 checkpointException_006: "Held for payment",
115 checkpointException_007: "Incorrect Address",
116 checkpointException_008: "Pick up missed",
117 checkpointException_009: "Rejected by carrier",
118 checkpointException_010: "Returning to sender",
119 checkpointException_011: "Returned to sender",
120 checkpointException_012: "Shipment damage",
121 checkpointException_013: "Shipment lost",
122 checkSpamFolder: "If you can't find the verification email, please check your spam and junk folders.",
123 codeExpiresIn: "Code expires in",
124 codeSentTo: "Code sent to",
125 codeWillExpire: "This code will expire in 10 minutes. If you didn't initiate this request, please let our support agents know.",
126 confirmed: "Confirmed",
127 createdAt: "Created at",
128 customerHasNoOrdersEmail: "No orders found for this email",
129 customerHasNoOrdersPhone: "No orders found for this phone number",
130 damagedInDelivery: "My order was damaged in delivery",
131 december: "Dec",
132 delivered: "Delivered",
133 deliveredAt: "at",
134 deliveredOn: "Delivered on",
135 deliveredVia: "Shipped via",
136 editOrder: "Edit order",
137 email: "Email",
138 errorFetchingOrders: "An error occurred while fetching your orders",
139 estimatedDelivery: "Estimated delivery",
140 etaProvidedBy: "ETA provided by",
141 expectToBeDeliveredBy: "by",
142 failedDelivery: "Failed delivery",
143 failedFulfillment: "Failed fulfillment",
144 failure: "Failure",
145 february: "Feb",
146 fillYourEmailToTalkToAnAgent: "Fill your email to talk to an agent",
147 findOrder: "Find your order",
148 fulfillment: "Fulfillment",
149 fulfillmentDetails: "Fulfillment details",
150 happyToHelp: "Happy to help, have a great day!",
151 hiFirstname: "Hi {{firstName}},",
152 howCanIHelp: "How can we help?",
153 iHaveTheFollowingIssue: "I have the following Issue:",
154 iWouldLikeToCancelTheFollowingOrder: "I'd like to cancel the following order",
155 iWouldLikeToReturnTheFollowingItems: "I'd like to return the following items",
156 inTransit: "In transit",
157 inTransitVia: "In-transit via",
158 incorrectOrder: "I did not receive the correct order",
159 invalidCode: "Invalid code",
160 invalidPhoneNumber: "Invalid phone number",
161 itemNames: "Item names",
162 itemsRequestedForReturn: "Items requested for return",
163 january: "Jan",
164 july: "Jul",
165 june: "June",
166 labelPrinted: "Label printed",
167 labelPurchased: "Label purchased",
168 lastUpdated: "Last updated",
169 learnMore: "Learn more",
170 lostOrderDetails: "Lost your order details? Talk to an agent",
171 manageYourOrders: "Manage your orders",
172 march: "Mar",
173 maxVerificationAttemptsReached: "Maximum verification attempts reached",
174 may: "May",
175 needHelp: "Need more help?",
176 noCustomerAssociatedEmail: "No customer associated with this email",
177 noCustomerAssociatedPhone: "No customer associated with this phone number",
178 noINeedMoreHelp: "No, I need more help",
179 november: "Nov",
180 october: "Oct",
181 of: "of",
182 oneItemSelected: "1 item selected",
183 order: "Order",
184 orderCreated: "Order Created",
185 orderNotFound: "We have no record of that order number and email combination. Please try again or ",
186 orderNumber: "Order number",
187 orderPlaced: "Order placed",
188 other: "Other",
189 outForDelivery: "Out for delivery",
190 outForDeliveryVia: "Out for delivery via",
191 partiallyRefunded: "Partially refunded",
192 pastDeliveryDate: "I'm past my expected delivery date",
193 payment: "Payment",
194 pendingDelivery: "Pending delivery",
195 pleaseRefreshPageToUseChat: "Please refresh your page to continue using the chat.",
196 pleaseUseVerificationCodeToLogIn: "Please use this verification code to complete your log-in:",
197 previousConversation: "Go to previous conversation",
198 processing: "Processing",
199 processingFulfillment: "Processing fulfillment",
200 provideEmailAndOrderNumber: "You must provide an email and an order number",
201 quantityToReturn: "Quantity to return",
202 quickAnswers: "Quick answers",
203 readyForPickup: "Ready for pickup",
204 reasonCancelOrder: "I'd like to cancel my order",
205 reasonCancelSubscription: "I'd like to cancel my subscription",
206 reasonChangeDeliveryDate: "I'd like to change the delivery date",
207 reasonChangeShippingAddress: "I'd like to change my shipping address",
208 reasonDidNotReceiveRefund: "I didn't get my refund",
209 reasonDiscountNotWorking: "My discount code is not working",
210 reasonEditOrder: "I'd like to edit my order",
211 reasonEditSubscription: "I'd like to edit my subscription",
212 reasonExchangeRequest: "I'd like to exchange items in my order",
213 reasonForgotToUseDiscount: "I forgot to apply my discount code",
214 reasonIncorrectItems: "The items are different from what I ordered",
215 reasonItemsMissing: "Some items are missing from my order",
216 reasonNotHappy: "I'm not happy with the product I received 👎",
217 reasonOrderDamaged: "My order was damaged in delivery",
218 reasonOrderDefective: "The items in my order are defective",
219 reasonOrderStillNotShipped: "My order should have shipped by now",
220 reasonOrderStuckInTransit: "My order has been stuck in transit",
221 reasonOther: "Other",
222 reasonPastExpectedDeliveryDate: "I'm past my expected delivery date",
223 reasonReorderItems: "I'd like to reorder some items",
224 reasonReplaceItemsRequest: "I'd like to replace items in my order",
225 reasonRequestDiscount: "I'd like a discount code",
226 reasonRequestRefund: "I'd like to get a refund for this order",
227 reasonReturnProduct: "I'd like to return a product",
228 reasonVeryHappy: "I'm very happy with the product I received 👍",
229 reasonWhereIsMyOrder: "Where is my order?",
230 refunded: "Refunded",
231 reportAnIssueWithOrder: "Report an issue with an order",
232 reportIssue: "Report issue",
233 reportIssueShort: "Report Issue",
234 requestCancellation: "Request Cancellation",
235 requestReturn: "Request Return",
236 resendCode: "Resend code",
237 return: "Return",
238 returnItems: "Return items",
239 returnOrder: "Return an order",
240 returnOrderShort: "Return Order",
241 see1MoreItem: "1 more item",
242 see1MoreOrder: "See 1 more order",
243 seeArticles: "See Articles",
244 seeMoreItems: "{moreItemsCount} more items",
245 seeMoreOrders: "See {nextPageOrderCount} more orders",
246 seeOrders: "See your orders",
247 selectAll: "Select all",
248 sendUsAMessage: "Send us a message",
249 sendCode: "Send code",
250 sent: "Sent",
251 september: "Sept",
252 severalItemsSelected: "{itemsSelectedCount} items selected",
253 shipmentBeingDelivered: "Order shipment is being delivered to its final destination.",
254 shipping: "Shipping",
255 shippingAddress: "Shipping address",
256 shippingInformation: "Shipping information",
257 showLessItems: "Show less",
258 signIn: "Sign in",
259 sincerely: "Sincerely,",
260 sms: "SMS",
261 sorryToHearThatEmailRequired: "Sorry to hear that. Leave us your email and we'll get back to you.",
262 sorryToHearThatEmailNotRequired: "Sorry to hear that! Someone will be with you soon.",
263 sorryToHearThatOfflineEmailCaptured: "Sorry to hear that, we'll get back to you by email.",
264 sorryToHearThatOnlineEmailCaptured: "I'm sorry to hear that. An agent will be with you in a few minutes.",
265 startConversation: "Start conversation",
266 stuckInTransit: "My order has been stuck in transit for several days",
267 subtotal: "Subtotal (Inc. tax)",
268 summary: "Summary",
269 supportTeam: "The {{shopFriendlyName}} support team",
270 talkToLiveAgent: "talk to a live agent",
271 thanksOurTeamWillRespond: "Thanks, our team will respond shortly.",
272 total: "Total",
273 track: "Track",
274 trackOrder: "Track an order",
275 trackOrderShort: "Track Order",
276 trackingNumber: "Tracking number",
277 trackingNumberPrefix: "Tracking no.",
278 trackingUrl: "Tracking Url",
279 trySigningInWithOrderNumber: "Try signing in with order number",
280 unavailable: "Unavailable",
281 unfulfilled: "Unfulfilled",
282 verificationCodeField: "6-digit code",
283 wasThisRelevant: "Was this relevant?",
284 whatIsWrongWithOrder: "What is wrong with your order?",
285 yesThankYou: "Yes, thank you",
286 yourEmail: "Your email",
287 yourOrders: "Your orders",
288 yourPhoneNumber: "Your phone number",
289 youWillGetRepliesHereAndByEmail: "Thanks! You'll get replies here and by email.",
290 youWillGetRepliesByEmail: "Thanks! You'll get replies by email.",
291 errorSendingReportIssue: "Something went wrong while sending the report issue."
292 }
293
294 window.GORGIAS_CHAT_TEXTS = chatDict
295 GorgiasChat.updateTexts(chatDict)
296 GorgiasChat.updateSSPTexts(sspDict)
297})
298</script>


Instructions for Shopify:

  1. Go to your Shopify's theme.liquid to edit the code.
    1. Navigate to your Shopify home screen.
    2. Click on 'Online Store' on the left.
    3. Select ThemesActionsEdit code.
    4. Under Layout, choose theme.liquid.
  2. Add the code:
    1. Copy the code above.
    2. Paste the code at the last line of the text code box.
  3. Edit the text of the item that you want to change.
    1. For example, you want to edit the message input placeholder ("Type a message...").
      1. If you want to change this, erase the text between the quotation marks.
  4. Click 'Save'.


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 GorgiasChat.init().then(function () {
4
5 var timer = setInterval(function () {
6 var chatButtonHead = document.querySelector('#gorgias-chat-container')?.querySelector('#chat-button')?.contentWindow.document.querySelector('head');
7 if (!chatButtonHead || ![...chatButtonHead?.children].some(x => x.getAttribute("data-emotion"))) {
8 return;
9 }
10 clearInterval(timer);
11
12 var buttonStyle = document.createElement('style');
13 buttonStyle.textContent = '#gorgias-chat-messenger-button {background-color: orange; transition: background-color 200ms ease;}'; // the custom CSS for the chat button
14 chatButtonHead.appendChild(buttonStyle);
15 }, 50);
16 })
17 </script>
18
19
20// Use this script to customize the chat window.
21 <script>
22 GorgiasChat.init().then(function () {
23 GorgiasChat.on('widget:opened', function () {
24 var timer = setInterval(function () {
25 var chatWindowHead = document.querySelector('#gorgias-chat-container')?.querySelector('#chat-window')?.contentWindow.document.querySelector('head');
26 if (![...chatWindowHead?.children].some(x => x.getAttribute("data-emotion"))) {
27 return;
28 }
29 clearInterval(timer);
30
31 var chatStyle = document.createElement('style');
32 chatStyle.textContent = '.message-window-iframe-1g7otri {box-shadow: none; background-color: lawngreen}'; // window header green
33 chatWindowHead.appendChild(chatStyle);
34 }, 50);
35 })
36
37 })
38 </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>
2GorgiasChat.init().then(function () {
3 var timer = setInterval(function () {
4 var chatButtonHead = document.querySelector('#gorgias-chat-container')?.querySelector('#chat-button')?.contentWindow.document.querySelector('head');
5 if (!chatButtonHead?.children.length) {
6 return;
7 }
8 clearInterval(timer);
9
10 var chatButtonIframe = document.querySelector('#chat-button');
11 chatButtonIframe.style = "display:none;"
12
13 // replace our button with your own var myButton = document.createElement('button');
14 myButton.style = `
15 position: fixed;
16 right: 100px; bottom: 10px;
17 z-index: 2147483000;
18 width: 50px;
19 height: 50px;
20 border-radius: 10px;
21 background-color: blue;
22 `
23
24 // onClick, behave like a chat opener
25 myButton.onclick = function () {
26 if (GorgiasChat.isOpen()) {
27 GorgiasChat.close();
28 } else {
29 GorgiasChat.open();
30 }
31 }
32 document.body.appendChild(myButton);
33 }, 50);
34});
35</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=conversationsets 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=mymessagewhere '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...


TIP: You can use online tools to encode a string such as urlencoder.org.


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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.isOpen() // Will return true or false.
4})
5</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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.isBusinessHours() // Will return true or false.
4})
5</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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.disableSSP()
4})
5</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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.enableOfflineMode() // Live chat OFF
4 GorgiasChat.disableOfflineMode() // Live chat ON
5})
6</script>


Set the current page of the chat

You can change the current page of the chat with this method:

1<script>
2GorgiasChat.init().then(function() {
3 // To show the conversation page.
4 GorgiasChat.setPage('conversation')
5
6 // To show the self-service screen.
7 GorgiasChat.setPage('homepage') // Note that the conversation page is showed if the self-service is disabled.
8})
9</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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.on('EVENT_NAME', function(data) {
4 // your code should go here
5 })
6})
7</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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.sendMessage('the message')
4})
5</script>


Note that if the chat is still closed, the message will wait for the user to open the chat before sending. If the chat remains always closed, the message will never be sent. If you want to send a message no matter what, force the opening of the chat first with 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>
2GorgiasChat.init().then(function() {
3 GorgiasChat.captureUserEmail('[email protected]');
4})
5</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}
8
9GorgiasChat.init().then(function() {
10 getCart().then(function(cart) {
11 GorgiasChat.captureShopifyCart(cart);
12 });
13})
14</script>


Additional features

Disable Segment

To disable Segment (a script used to gather analytics) use the following script:

1<script>
2GorgiasChat.init().then(function() {
3 GorgiasChat.disableSegment()
4})
5</script>


Note that it should be placed at the top of the customization scripts, so that the script doesn't get triggered by another API request.


Remove the chat based on country code
This feature requires an ipstack account. Free accounts are limited to 5,000 requests. 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 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 key
4var ipstackAPIKey = 'YOUR_API_KEY'
5// set your country code whitelist
6var countryCodeWhiteList = ['US', 'MX']
7// set this to false if you only have a free tier account for ipstack
8var useHttps = true
9
10function removeGorgiasChat(countryCode) {
11 GorgiasChat.init().then(function() {
12 var container = document.querySelector('#gorgias-chat-container');
13 if (container && !countryCodeWhiteList.includes(countryCode)) {
14 container.remove()
15 }
16 })
17}
18
19var countryCode = window.localStorage.getItem('countryCode')
20if (!countryCode) {
21 protocol = useHttps ? 'https' : 'http'
22 $.ajax({
23 url: protocol + '://api.ipstack.com/check?access_key=' + ipstackAPIKey + '&fields=country_code',
24 dataType: 'jsonp',
25 success: function (json) {
26 if (json && json.country_code) {
27 countryCode = json.country_code
28 } else {
29 countryCode = 'unknown'
30 }
31 window.localStorage.setItem('countryCode', countryCode)
32 removeGorgiasChat(countryCode)
33 },
34 error: function (request, status, error) {
35 console.error(request.responseText);
36 window.localStorage.setItem('countryCode', 'unknown')
37 removeGorgiasChat('unknown')
38 }
39 })
40} else {
41 removeGorgiasChat(countryCode)
42}
43</script>


Instructions for Shopify:

  1. Go to your Shopify store's theme.liquidto edit the code.
    1. Navigate to your Shopify home screen.
    2. Click on 'Online Store' on the left.
    3. Select ThemesActionsEdit code.
    4. Under Layout, choose theme.liquid.
  2. Add the code:
    1. Copy the code above and paste it on the code text box.
    2. Enter your ipstack API key where the code says 'YOUR_API_KEY'.
    3. Enter the country code/s where you only want to display the chat widget where it says ['US', 'MX'].
    4. 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.
  3. Click on 'Save'. The chat won't be available to anyone except for shoppers from the countries you entered.


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.

Uninstalling and reinstalling the Chat from Shopify using the One-click installation can cause this. Please review the theme files scripts order.


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 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:

  1. Go to your Shopify store's theme.liquid to edit the code.
    1. Navigate to your Shopify home screen.
    2. Click on 'Online Store' on the left.
    3. Select ThemesActionsEdit Code.
    4. Under Layout, choose theme.liquid.
  2. Add the code:
    1. Copy the code above.
    2. Paste it on the first line or the last line in the text code box.
  3. 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]



Was this article helpful?
Yes
No