Troubleshoot chat widget not appearing on website pages

When you set up a live chat or rule-based chatbot, the chat widget may not appear on the expected website pages or for the intended contacts. This article outlines common causes and provides troubleshooting steps to help you resolve the issue. 

Make sure the tracking code is installed

If you're adding a chatflow to a website that is hosted externally from HubSpot, you need to install the HubSpot tracking code on your pages. You can access your tracking code in your settings:

Please note: if you already have the HubSpot tracking code installed on your website, or if your website is hosted on HubSpot, you do not need to install this code snippet separately.

1. In your HubSpot account, click the settings icon in the top navigation bar.
2. In the left sidebar menu, navigate to Tracking & Analytics > Tracking Code.
3. To copy the code and add it to your website, click Copy. Or click Email to developer and enter an email address to send the code to your web developer or IT resource.

If the tracking code was added manually, make sure the exact snippet was copied without modification and installed in your page header where expected. If you're using a tag manager, confirm the HubSpot tag is publishing and firing on the page you're testing.

Check for script blockers or cookie consent restrictions

If the chat widget still isn’t appearing, check whether a cookie consent banner, script blocker, or other third-party or custom JavaScript is preventing HubSpot’s tracking script from loading. Some consent management platforms block HubSpot scripts until a visitor accepts cookies, which can prevent the chat widget from displaying.

Work with your developer to ensure that HubSpot scripts are allowed to run when appropriate, and verify that no third-party tools or browser extensions are blocking HubSpot scripts from loading. 

Check that the HubSpot tracking code and chat widget scripts are loading correctly 

Once the tracking code is installed, verify that it’s loading correctly on your page.

The tracking code should appear in the page source or DOM with the id attribute hs-script-loader.

HubSpot uses specific script id attributes to prevent the same script from being loaded more than once. Don’t use HubSpot script IDs elsewhere on your website. If another page element already uses the same ID, HubSpot may determine the script is already present and not load it again.

To confirm the chat widget scripts are loading:

1. Open your website in a browser.
2. Open developer tools, then check the Network tab.
3. Search for conversations-embed.js. This file is loaded by the HubSpot tracking code and should come from a domain that includes usemessages.
4. Confirm that the script has the id attribute hubspot-messages-loader and includes the required data attributes:
• data-hsjs-portal
• data-hsjs-hublet
• data-hsjs-env
5. Search for visitor.js. This script loads the chat widget UI and is inserted by conversations-embed.js.

If conversations-embed.js or visitor.js doesn’t load, check the browser console for JavaScript errors, Content Security Policy errors, or other page errors that may prevent HubSpot scripts from running.

Please note: if no chatflows are turned on in the account, the tracking code may not include the code that loads conversations-embed.js. After turning on a chatflow, there may be caching before the updated tracking code starts loading the chat widget script.

If your site enforces a Content Security Policy (CSP), make sure HubSpot script domains are allowed. CSP-related errors typically appear in the browser console and indicate which script was blocked and why. Learn more about required domains and directives in HubSpot’s Content Security Policy settings.

Turn the chatflow on

To confirm that the chatflow is turned on:

1. In your HubSpot account, navigate to Service > Chatflows.
2. Next to the inactive chatflow, in the Status column, click to toggle the status switch on.
   

Clear your browser cache

If the chatflow doesn't appear on your website after you turn it on, verify that you're testing on the correct live domain or environment. If you've recently made changes to your site, wait a few minutes or refresh the page.

Then, try loading your website in an incognito browser window. If the chatflow appears in incognito, clear your browser cache and cookies to view the chatflow in a non-incognito browser window.

Review your targeting and exclusion rules

When building a chatflow, you can specify which pages the chat widget should appear on in your targeting settings. You can also target based on known information about the visitor. Review your targeting rules on the chatflow's Target tab to make sure the criteria matches what you expect to see on your website pages.

Specify the correct domain and subdomain

First, verify that the page where you're expecting to see the chatflow is included in your targeting rules. If you want the chatflow to appear on pages on a specific domain, make sure to enter the correct domain. For example, if your targeting rule is Website | contains | www.coffeeshop.com, the chatflow will appear on any page hosted on the www subdomain, including www.coffeeshop.com, www.coffeshop.com/contact, and www.coffeeshop.com/pricing.

However, the chatflow will not appear on blog.coffeeshop.com unless you add the blog subdomain to your targeting rules.

Or, you can specify the root domain in your targeting rules. In this example, if you use the targeting rule Website | contains | coffeeshop.com, the chatflow will appear on any page with this root domain.

Confirm the page URL used for targeting

When the chat widget loads, it sends the page URL to HubSpot to determine whether a chatflow should appear based on your targeting rules.

To check which URL is being used:

1. Open your website in a browser.
2. Right-click anywhere on the page and select Inspect, or press Ctrl + Shift + I (Windows) or Cmd + Option + I (Mac) to open developer tools.
3. Click the Network tab.
4. Refresh the page.
5. Look for a request related to the chat widget (for example, a request that includes conversations or messages).
6. Click the request, then check the Headers tab.
7. Find the X-Hubspot-Messages-Uri header and review its value.

Confirm that the URL in this header matches your chatflow targeting rules. For example, a targeting rule that contains https://hubspot.com won’t match a URL that starts with https://www.hubspot.com if the rule doesn’t include the www subdomain.

If your site uses reverse proxying, make sure the proxy preserves the X-Hubspot-Messages-Uri header when forwarding requests to HubSpot. Without this header, the chat widget may not load as expected.

Check exclusion rules

If the chatflow does not appear as expected, make sure the page URL is not included in your exclusion rules. Navigate to your chatflow, then on the Target tab, review and remove any exclusion rules as needed.

Verify visitor information and behavior

If you're targeting your chatflows based on visitor information and behavior, make sure the contact meets the target criteria. For example, if your chatflow only appears to a contact who clicked a specific CTA on your website, navigate to the contact record and filter for the contact's CTA activity. If the contact has not clicked the selected CTA, they will not see the chatflow.

If they did click the CTA, review the additional troubleshooting steps in this guide or learn more about how tracking cookies can impact whether the chatflow appears.

Check single-page applications (SPAs)

If your website is a single-page application, or SPA, your targeting rules might not work as expected because of how an SPA's website content dynamically updates when you navigate to other pages, instead of reloading. HubSpot cannot detect the new page URL, which can cause the wrong chatflow to appear on a page, or prevent it from appearing at all. If you're using a live chat or bot on your single-page app, it is recommended to work with a developer to use the Chat widget SDK to target your pages. Use the .widget-refresh method to specify different chatflows on different pages. Learn more on HubSpot's developer docs.

Check chat availability settings

If your chatflow still isn't appearing on your pages, check your chat channel's availability settings. You can control when to hide the chat widget, including when no team member is online or when it's outside of business hours, by editing your availability settings:

1. In your HubSpot account, click the settings icon in the top navigation bar.
2. In the left sidebar menu, navigate to Inbox & Help Desk:
   • To edit a chat channel connected to the conversations inbox, select Inbox.
   • To edit a chat channel connected to help desk, select Help Desk. Then, under Ticket sources and routing, click Channels.
   • Hover over the chat channel and click Edit.
3. Navigate to the Availability tab. Select an option:

• • Based on user availability: visitors can chat with your team if at least one team member assigned in your assignment rules is available.
  • Based on chat operating hours: set when your team should appear available to chat and let visitors know when they can expect a reply.
    
    • Use the dropdown menus to set your team’s operating hours. Click + Add hours to add additional day and time ranges.
    • Chat is available 24/7: select this checkbox if your team always appears available to chat.

4. In the Availability behavior section, configure the chat experience based on your team's availability and let visitors know when they can expect a reply. Select an option:

• • To set up the visitor's experience when your team is available, click the Available tab. Click the Show typical reply time dropdown menu to let visitors know when they can expect a reply.
  • To set up the visitor's experience when your team is away during business hours, click the Away tab. Click the Show an away message dropdown menu and select an away mode widget behavior.
    
    
    

  Subscription required A Service Hub Enterprise subscription is required to set a visitor's experience when your team is at max capacity.

  • To set up the visitor's experience when your team is at max capacity, click the If all team members are at max capacity, then dropdown menu and choose to either show a wait message, hide the chat launcher or do nothing. Learn more about configuring chat capacity limits for users.

• • To set up the visitor's experience outside of your team's working hours, click the Outside working hours tab and click the Set offline behavior dropdown menu and choose to either show return time, show an away message, or hide the chat launcher when a visitor comes to your site outside of business hours.

5. Click Save.

If you're using a chatflow that includes a bot, the chatflow might still appear if you haven't customized the bot's availability preferences. Learn how to edit when the chatflow should display based on your team's availability.

Check chatflow prioritization

When you have more than one chatflow that appears on a page, you can decide which one HubSpot should prioritize when a visitor comes to your site. If the expected chatflow is not appearing, check the chatflow's priority compared to the other chatflows on your page.

Understand why a different chatflow appears

If a visitor started a thread on one of your pages, then navigates to another page where a different chatflow is supposed to appear, the conversation will continue in the original thread. Therefore, the other chatflow will not appear. For example:

• Chatflow A is supposed to appear on www.coffeeshop.com.
• Chatflow B is supposed to appear on blog.coffeeshop.com.
• A visitor started a chat with Chatflow A, then navigated to blog.coffeeshop.com.
• Chatflow B will not appear and the visitor can continue the thread that they started with Chatflow A.

Understand tracking cookies

If after following the steps above your chat widget is still not appearing for the contacts that meet your target criteria, this is most likely due to tracking cookies. For your chat widget to appear for a visitor, a tracking cookie must be associated with the visitor's contact record in your contact database. If the contact record does not have a tracking cookie, then your chat widget will not appear for the visitor associated with the contact record.

How does a visitor get a tracking cookie?

Visitors are tracked anonymously with a tracking cookie before becoming contacts. HubSpot can then associate their website activity on the tracking cookie with their contact record in two ways:

• The visitor fills out a HubSpot form.
• The visitor clicks through a HubSpot Marketing email leading them to a HubSpot page or to a non-HubSpot page with the HubSpot tracking code installed.

Additionally, you can use the tracking code API to track visitors to your site.

Until the visitor performs one of the conversions above, HubSpot doesn't know who the visitor is or what lists the visitor's contact record is part of. Therefore, if you have a contact that hasn't converted yet, they won't see your chat widget even if they're a contact in your database or a member of the list you're targeting to.

Please note: even if the visitor has done one of the two actions above to get a tracking cookie, if the visitor has since deleted browser cookies or visited your site in a different browser, in an incognito window, or on their mobile device, then their tracking cookie can't be detected and your chat widget won't appear for them.

Why do I have contacts without a tracking cookie?

Here are a few common ways contacts can exist in your database without converting on a form or clicking a marketing email link:

• The contact was imported.
• The contact was added manually.
• The contact was created from a logged sales email.

Once a contact in your database is tracked with a tracking cookie, then HubSpot considers them a known contact. If they meet your audience criteria, your chat widget will appear for them when they visit your site.

Please note: in some cases, some browser extensions (such as pop-up, ad, or script blockers) may prevent the chat widget from loading. If the widget appears after disabling these extensions, one of them is likely blocking it.