Gorgias logo
Gorgias logo
All articles

Customize the chat widget with HTML and JavaScriptUpdated 17 minutes ago

Who can use this feature?

 
Only the account owner and admins can modify the chat widget
 
All Helpdesk plans
 
Available for Shopify and BigCommerce stores connected to Gorgias

Advanced HTML and JavaScript customization lets you extend the Gorgias chat widget beyond what's available in the settings — things like controlling when the widget appears, pre-filling messages, hiding the widget on specific pages, or injecting custom CSS. This article explains how the customization layer works and where to place your code so it runs in the right order.

Note: Advanced chat customization requires working knowledge of HTML, JavaScript, and — for Shopify stores — Shopify Liquid. These customizations are outside the scope of what Gorgias support can troubleshoot. If something isn't working as expected, your development team will need to debug it.

How HTML and JavaScript customization works

The Gorgias chat widget exposes a JavaScript API through a global object called GorgiasChat. Once the widget is loaded on your page, you can call methods on this object to control widget behavior programmatically — opening or closing the widget, hiding it on mobile, capturing a customer's email, sending a message on their behalf, and more.

Because the widget loads asynchronously, you can't call GorgiasChat methods the moment your page loads. You first need to wait for the widget to finish initializing. The recommended way to do this is:

1var initGorgiasChatPromise = (window.GorgiasChat)
2    ? window.GorgiasChat.init()
3    : new Promise(function (resolve) {
4        window.addEventListener('gorgias-widget-loaded', function () { resolve(); })
5    });
6

7initGorgiasChatPromise.then(function () {
8    // Your custom code goes here
9});
10

This pattern handles two cases: if GorgiasChat is already present on the window (because the widget loaded before your script ran), it calls init() directly; if not, it waits for the gorgias-widget-loaded event to fire before proceeding. You should use this wrapper for all customizations.

Note: Never call GorgiasChat methods directly in a script tag without the init wrapper. If your script runs before the widget has loaded, you'll get an "Uncaught ReferenceError: GorgiasChat is not defined" error in the console.

Where to place custom code

All custom scripts must be placed after the Gorgias chat installation snippet, within the <body> tags of your page. The order matters — your script needs the widget's bundle loader to be present on the page before it runs, and the init() promise handles the rest.

Your installation snippet looks like one of these:

1<!-- Version 2 -->
2<script id="gorgias-chat-widget-install-v2"
3    src="https://config.gorgias.chat/gorgias-chat-bundle-loader.js?applicationId=XXXXX">
4</script>
5

6<!-- Version 3 -->
7<script id="gorgias-chat-widget-install-v3"
8    src="https://config.gorgias.chat/bundle-loader/XXXXXXXXXXXXXXXXXXXXXXXXXX">
9</script>
10

Your custom <script> tag goes directly after this, still inside <body>:

1<script id="gorgias-chat-widget-install-v3"
2    src="https://config.gorgias.chat/bundle-loader/XXXXXXXXXXXXXXXXXXXXXXXXXX">
3</script>
4

5<script>
6var initGorgiasChatPromise = (window.GorgiasChat)
7    ? window.GorgiasChat.init()
8    : new Promise(function (resolve) {
9        window.addEventListener('gorgias-widget-loaded', function () { resolve(); })
10    });
11

12initGorgiasChatPromise.then(function () {
13    // Your custom code goes here
14});
15</script>
16

On Shopify stores

Shopify stores have two options depending on whether you want the customization to apply globally or only to specific pages.

To apply customization globally (all pages), add your custom script to your store's theme.liquid file:

  1. From the Shopify admin, click Online Store in the left sidebar.
  2. Click Themes.
  3. Next to your active theme, click the  three dots icon, then select Edit code.
  4. In the menu, locate Layout, then select theme.liquid.
  5. Find your Gorgias chat installation snippet in the file.
  6. Paste your custom <script> tag immediately after the installation snippet, before the closing </body> tag.
  7. Click Save.

To apply customization to a specific page only, add your custom script to that page's content area using Shopify's HTML editor:

  1. From the Shopify admin, select Online Store in the left sidebar, then click Pages.
  2. Select the page you want to edit from the list.
  3. In the Content area, click the Show HTML icon (the <> button).
  4. Paste your custom <script> tag into the HTML view.
  5. Click Save.
Note: If your store was set up using the Quick installation for Shopify method, adding advanced customization requires switching to manual installation. Quick install re-injects the chat in its default state each time it runs, which removes any custom code you've added to the theme files. Review the order of scripts in your theme files if your customizations stop working after reinstalling.

On BigCommerce stores

BigCommerce handles <script> tags and non-script code (like CSS overrides) differently.

To add script-based customizations, use the Manage Code feature in BigCommerce:

  1. From the BigCommerce control panel, go to Manage Code.
  2. Add your custom <script> tag as a new script entry.
  3. Save your changes.

To add non-script customizations — such as style overrides that use a <style> tag instead of a <script> tag:

  1. From the BigCommerce control panel, go to Theme Manager.
  2. Click Edit Theme next to your active theme.
  3. Locate the home.html file.
  4. Add your custom code to the file.
  5. Save your changes.

Available API methods

The GorgiasChat object exposes a number of methods you can call inside the init() callback. The most commonly used ones are:

  • GorgiasChat.open() — opens the chat window
  • GorgiasChat.close() — closes the chat window
  • GorgiasChat.isOpen() — returns true if the chat window is currently open
  • GorgiasChat.hideOnMobile(true) — hides the widget on mobile devices
  • GorgiasChat.hideOutsideBusinessHours(true) — hides the widget when outside business hours
  • GorgiasChat.isBusinessHours() — returns true if the current time is within configured business hours
  • GorgiasChat.isChatOnline() — returns true if agents are currently online
  • GorgiasChat.captureUserEmail('[email protected]') — associates an email address with the current chat session
  • GorgiasChat.sendMessage('Your message here') — sends a message on behalf of the visitor
  • GorgiasChat.setCurrentInput('Hello!') — pre-fills the chat input field
  • GorgiasChat.updateTexts({}) — overrides default label text in the widget
  • GorgiasChat.setPosition(position) — sets the widget's position on the page
  • GorgiasChat.disableAttachments() — disables the file attachment option
  • GorgiasChat.disableSegment() — disables Segment analytics tracking
  • GorgiasChat.setShouldOpenLinksInNewPage(true) — forces links in the chat to open in a new tab

To see example code for each of these methods, see our HTML snippets for chat customization article.

FAQ

I'm getting "Uncaught ReferenceError: GorgiasChat is not defined" — what does that mean?

This error means either the Gorgias chat installation snippet is missing from the page, or your custom script is running before the chat bundle has loaded. Make sure your custom <script> tag appears after the installation snippet in the HTML, and that you're using the init() promise wrapper rather than calling GorgiasChat methods directly.

Also check that your installation snippet has the correct script id: gorgias-chat-widget-install-v2 for version 2 snippets, or gorgias-chat-widget-install-v3 for version 3 snippets. If you recently switched from Quick installation on Shopify, check the order of scripts in your theme files — a re-install can place the Gorgias snippet in a position that interferes with custom code that was there before.


Was this article helpful?
Yes
No