Launch HubSpot Chat Widget in Minutes for Marketers and Developers

HubSpot’s chat widget is a built-in messaging tool inside Chatflows and HubSpot CRM that you can publish on a live website in minutes. Marketers add it by creating a chatflow, choosing a display style, and publishing (or embedding the HubSpot tracking code on external sites). Developers get finer control through the Conversations Chat Widget SDK, which loads, refreshes, and manages the widget programmatically. Either way, the next move is the same: build the chatflow first, then decide how much custom control you actually need.

---

TL;DR:

• Proper installation of the HubSpot tracking code on all relevant pages is essential for the chat widget to display correctly, especially on external sites.
• Customizing the widget’s appearance, such as colors, avatars, fonts, and placement, should be previewed across device types to avoid layout issues and reinforce branding.
• Selecting the appropriate availability mode—based on user status, operating hours, or always-on—is crucial to prevent misaligned expectations and missed conversations.
• Careful configuration of targeting rules ensures chat only appears on intended pages and segments, with testing in incognito mode to catch rules that are too narrow or misapplied.
• Developers should leverage the SDK for programmatic control, especially for SPA sites, to refresh, open, or close the widget reliably during route changes without causing display errors.

---

Table of Contents

• How Do You Set Up the HubSpot Chat Widget?
• Customize Appearance and Brand: Colors, Avatar, Fonts, and Placement
• Availability, Routing, and Capacity: Who Answers and When
• Targeting Rules: Page-Level Display and Personalization
• Chatflow Types: Live Agent, Bots, and Mobile
• Developer Guide: The Conversations Chat Widget SDK
• Single-Page Apps: Refresh, Cookies, and Missing Widget Fixes
• Testing, Previewing, and Publishing the Chatflow
• How Chat Integrates with HubSpot CRM and Workflows
• Best Practices and Launch Checklist
• Implementation Checklist With Owner Assignments
• When HubSpot Chat Fits, and When It Doesn’t
• Get Your Chat Widget Live Without the Manual Setup Work
• Official HubSpot Resources Worth Bookmarking
• Sources

How Do You Set Up the HubSpot Chat Widget?

Getting chat live on your site starts in one place: Service > Chatflows inside your HubSpot account. From there, HubSpot walks you through a setup dialog that covers display, behavior, and availability before anything goes public.

Here’s the exact path:

1. Navigate to Service > Chatflows and click “Create chatflow.”
2. Select “Website” as the channel type (as opposed to Facebook Messenger or a custom SDK integration).
3. Work through the “Set up chat” dialog, which opens with three main tabs: Display, Chatflow, and Availability.
4. On the Display tab, name your chatflow internally, write your welcome message, and set who the chat appears to represent (a person, a team, or your brand).
5. On the Chatflow tab, build the actual conversation flow: a simple greeting that hands off to a live agent, or a bot sequence that asks qualifying questions first.
6. On the Availability tab, define when the widget shows as online, away, or hidden entirely (more on this below).
7. Preview the chatflow using the preview panel before you touch the publish toggle. This renders exactly what a visitor will see, including your welcome text and avatar.
8. Toggle “Publish” once you’re satisfied. HubSpot activates the chatflow immediately on any page where your tracking code is installed.

If your site isn’t built or hosted on HubSpot, you need the HubSpot tracking code on every page where you want chat to appear. HubSpot generates this snippet automatically once you create your first chatflow, and it should sit right before the closing </head> tag, per HubSpot’s own setup instructions. Miss this step, and your chatflow can be published, styled, and perfectly configured, and still never show up for a single visitor.

Pro Tip: Publish the chatflow in a “paused” or narrowly targeted state first (limit it to a staging URL or your own IP-based query parameter), confirm it renders correctly, then widen the targeting rules once you’ve verified the tracking code fired.

One detail trips up a lot of teams: the tracking code and the chatflow are two separate systems. The code has to load on the page before HubSpot can even check whether a chatflow should display, which is exactly why so many “the widget isn’t showing” tickets trace back to a missing or misplaced script rather than a broken chatflow.

Customize Appearance and Brand: Colors, Avatar, Fonts, and Placement

Chat that looks like a generic support widget undercuts trust before a visitor types a single word. HubSpot lets you adjust the visual identity directly inside the chatflow editor, and the customization controls cover more ground than most teams realize.

Inside the Display tab, you can set:

• Accent color using an exact hex code, so the widget bubble and header match your existing brand palette instead of a default HubSpot blue.
• Avatar or logo for the chat representative, either a real photo for a live-agent feel or your company logo for a brand-first tone.
• Font selection, pulled from a curated list that keeps the widget legible without letting it clash with your site’s typography.
• Launcher placement, choosing left or right corner positioning to avoid colliding with existing on-page elements like a cart icon or a cookie banner.
• Widget behavior, either a floating launcher bubble or an inline embed anchored to a specific page element using an inlineEmbedSelector in the tracking code configuration.

The inline option matters more than it sounds. A floating bubble is fine for general site-wide support, but if you’re running a pricing page or a demo request form, embedding the widget directly into the page layout (rather than as a corner overlay) tends to keep visitor attention on the conversion action instead of competing with it.

Pro Tip: Preview your chatflow at three breakpoints, desktop, tablet, and mobile, before publishing. A launcher position that looks clean on a 15-inch laptop screen can sit awkwardly over a mobile “Buy Now” button, and HubSpot’s preview panel lets you catch that before a real visitor does.

Font and color changes apply instantly in preview, so there’s no reason to guess. Make one change, check the render, move to the next. It’s a five-minute pass that saves you from shipping a widget that fights your brand instead of reinforcing it.

Availability, Routing, and Capacity: Who Answers and When

A chat widget that promises “we’re online” when nobody is actually watching the inbox does more damage than not having chat at all. HubSpot gives you three availability modes on the Availability tab, and picking the right one depends on how your team actually staffs support.

Your options break down like this:

• Based on assigned users’ status, where the widget shows online only when a specifically assigned team member is logged in and marked available.
• Based on operating hours, where you define a weekly schedule and the widget switches to away automatically outside those windows.
• Always available, which keeps the widget live around the clock and routes overnight or after-hours messages into the inbox for the next available person.

When the widget goes into away or offline mode, you control what happens next. You can show an estimated return time, hide the launcher entirely until hours resume, or keep the launcher visible but switch the flow to capture a name, email, and message instead of promising a live response.

Assignment settings determine where conversations land once someone starts chatting. You can route to specific users, to a team, or let capacity rules distribute load so one person doesn’t get flooded while others sit idle. HubSpot recommends pairing this with real-time notifications, particularly through Slack integration and the HubSpot mobile app, so an assigned rep sees a new conversation the moment it starts rather than discovering it hours later in the inbox. For small teams running lean, that notification layer often matters more than any other setting on this tab.

Targeting Rules: Page-Level Display and Personalization

Not every page needs the same chat experience, and showing a generic sales bot on your careers page or a support-only chatflow on your checkout flow wastes the conversation before it starts. HubSpot’s targeting rules let you control exactly where a chatflow appears.

The controls you’ll use most:

• Website URL rules, which let you specify exact URLs, URL patterns, or exclusions so a chatflow only fires on the pages it’s meant for.
• Query parameter rules, useful for showing a specific chatflow only to visitors arriving from a particular campaign link or ad, by matching a UTM or custom parameter.
• Combined criteria, stacking a URL rule with a query parameter or a known visitor property so the chatflow narrows to a precise segment rather than “everyone on this page.”
• Known visitor targeting, where returning contacts with existing HubSpot properties (lifecycle stage, deal status, or a custom field) can see a different chatflow than a first-time anonymous visitor.

Test targeting rules the same way every time: open the exact URL you configured, in a private or incognito window, with no existing HubSpot cookies from a prior session. That clean-state test catches the two most common mistakes: a URL rule that’s slightly too narrow (missing a trailing slash or a parameter case mismatch) and a chatflow that’s technically published but paused at the account level. If a widget that should be showing isn’t, the URL rule is the first thing worth rechecking, before you assume the whole setup is broken.

Chatflow Types: Live Agent, Bots, and Mobile

HubSpot chatflows split into a few practical categories, and picking the right one depends on what you’re actually trying to accomplish, not which one looks the most advanced.

Live agent chatflows work best when conversations need a human judgment call: sales qualification, pricing negotiation, or support cases where a scripted bot would just frustrate someone. Rule-based bots shine at repetitive triage: qualifying a lead before a rep gets involved, routing a support question to the right team, or booking a meeting without anyone typing a single message manually.

Useful bot automations worth building on day one:

• Capture an email address before a conversation goes further, so even an abandoned chat leaves you a way to follow up.
• Book a meeting directly through the chat window, syncing to a rep’s calendar without a separate scheduling link.
• Create a support ticket automatically when a visitor describes an issue, skipping the “please email support@” hand-off entirely.
• Offer knowledge base browse and search inside the chat window, so visitors can self-serve an answer before a human ever gets pulled in.

That knowledge base option deserves more attention than it usually gets. A visitor who finds their own answer in ten seconds is a better outcome than one who waits four minutes for a rep, even a fast one. If you’re also thinking about how visitors search for content on your site more broadly, a conversational search audit can show where self-service content gaps are pushing people into chat unnecessarily.

Mobile chatflows extend the same logic into a native app context through HubSpot’s mobile chat SDK, which is worth a separate look if your product lives partly or entirely outside the browser.

Developer Guide: The Conversations Chat Widget SDK

Marketers get most of what they need from the chatflow editor. Developers who need programmatic control, custom triggers, or tighter integration with an app’s own state management reach for the Conversations Chat Widget SDK instead.

The core object is window.HubSpotConversations, injected by the tracking script once it loads. Because that injection isn’t guaranteed to happen before your own code runs, wrap any widget commands in window.hsConversationsOnReady, which queues your calls until the object actually exists.

The methods you’ll use most often:

• widget.load() initializes and displays the widget on demand, useful when you don’t want chat loading automatically on page render.
• widget.refresh() re-evaluates targeting and configuration, essential after any client-side navigation.
• widget.open() and widget.close() toggle the chat panel programmatically, handy for triggering chat from a custom button.
• widget.remove() tears the widget down entirely, and widget.status() reports whether it’s currently loaded.

Configuration fields worth knowing include loadImmediately (control whether the widget appears on load or waits for an explicit call), inlineEmbedSelector (anchor the widget to a specific page element instead of a floating launcher), and enableWidgetCookieBanner (control whether HubSpot’s own cookie consent prompt shows before the widget initializes).

For events, listen for conversationStarted to trigger your own analytics event, widgetLoaded to confirm the widget rendered successfully, contactAssociated to know exactly when a chat gets tied to a CRM contact record, and widgetClosed to fire any follow-up UI logic.

Pro Tip: widget.refresh() is throttled to roughly one call per second, so don’t wire it to something that fires constantly, like a scroll listener. Router navigation events are the right trigger; scroll or resize events will just get dropped.

Single-Page Apps: Refresh, Cookies, and Missing Widget Fixes

Single-page apps break the assumption HubSpot’s tracking script was originally built on: that a new page load means a new page. When your app changes routes without a full reload, the widget has no idea the URL changed unless you tell it.

The fix is a single call, placed correctly:

1. Hook into your router’s navigation event (React Router’s useLocation, Vue Router’s afterEach, or the equivalent in your framework).
2. Call widget.refresh() on every route change so URL-based targeting rules re-evaluate against the new path.
3. Remember the throttling limit. Rapid consecutive route changes within the same second will drop extra refresh calls rather than queue them.
4. Expect the widget to disappear on some routes. If the new route has no matching chatflow and there’s no active conversation, refresh() will legitimately remove the widget rather than leave a stale, mistargeted bubble behind.

If you’re deploying a React-based site, WebsitePublisher.ai’s React deployment guide covers similar route-change patterns worth applying alongside your chat refresh logic.

When the widget doesn’t appear at all, work through a fixed checklist rather than guessing: confirm the tracking code is actually installed on that page (view source, don’t just trust memory), confirm the chatflow is published and not paused, and check for the HubSpot tracking cookie in your browser’s dev tools. A missing cookie or an uninstalled script is the leading cause when targeting rules technically match but nothing renders. For a clean testing state, widget.clear() removes the current visitor’s chat cookies, letting you simulate a brand-new visitor without switching browsers.

Testing, Previewing, and Publishing the Chatflow

Every chatflow deserves a real test pass before it goes live, not just a glance at the preview panel.

1. Toggle through preview device sizes inside the chatflow editor, checking desktop, tablet, and mobile renders individually.
2. Test your exact targeting rules by visiting the precise URLs and query parameters you configured, not a close approximation.
3. Use a private or incognito browser window for each test so leftover cookies from earlier sessions don’t mask a targeting bug.
4. Check the Conversations inbox after each test chat to confirm the message arrived and that a contact record was created or updated.
5. Verify the tracking code fired on external (non-HubSpot-hosted) pages by inspecting the page source for the script tag.
6. Flip the publish toggle only after every check above passes, not before.

This sequence catches the two failure modes that cause the most support tickets: a targeting rule that’s narrower than intended, and a tracking code that’s present in staging but never made it to production.

How Chat Integrates with HubSpot CRM and Workflows

Every conversation through the chat widget becomes part of the contact’s permanent record automatically, which is the single biggest reason teams already living in HubSpot’s CRM choose its chat over a standalone widget. There’s no export, no manual tagging, no separate tool to check.

What that logging enables in practice:

• Historical context for follow-up, so a sales rep opening a contact record six weeks later can read the exact chat exchange that first brought that lead in.
• Automatic contact association, triggered by the contactAssociated event, which fires the moment HubSpot ties an anonymous chat session to a known or newly created contact.
• Workflow triggers, letting you kick off an email sequence, assign a task, or create a support ticket the instant a chat matches specific criteria (a keyword, a form field, a chatflow completion).
• Ticket creation directly from chat, useful when a conversation surfaces a genuine support issue rather than a sales question.

One caveat worth stating plainly: exactly how much data gets captured, retained, and surfaced depends on your account’s own settings and the region your business operates in, since privacy rules like consent requirements vary by jurisdiction. Don’t assume a default configuration applies universally. If your business serves visitors across multiple regions, check your chat and cookie consent settings against the privacy rules that actually apply to each one, rather than treating HubSpot’s default setup as automatically compliant everywhere.

Best Practices and Launch Checklist

A widget that’s technically installed correctly can still perform poorly if the basics of the conversation itself are off. A few defaults consistently outperform a bare “Hi, how can we help?”:

1. Write a specific welcome message, naming what the visitor is looking at (“Questions about pricing? I’m happy to help”) rather than a generic greeting.
2. Display a realistic expected reply time, so visitors don’t wait indefinitely on a promise you can’t keep.
3. Capture a fallback email when offline, converting an unanswered visit into a lead you can follow up on later.
4. Check tap target size on mobile, since a launcher bubble that’s easy to click on desktop can be maddening to hit accurately on a phone screen.
5. Confirm keyboard focus and contrast for accessibility, particularly for visitors using screen readers or keyboard-only navigation.
6. Consider deferring widget load on performance-sensitive pages, and lean on inline embedding for high-intent conversion pages where a floating bubble competes with your call to action.

Area	What to Monitor	Why It Matters
Response speed	Time from first message to first reply	Slow replies are the top reason visitors abandon chat
Conversion	Chats that become contacts or deals	Confirms the widget is driving pipeline, not just messages
Coverage	Percentage of published pages with confirmed tracking code	Catches silent gaps before they cost you a lead

Implementation Checklist With Owner Assignments

Handing off chat setup across a marketing and development team goes faster with clear ownership from the start.

1. Install the HubSpot tracking code on every relevant page. Owner: developer.
2. Create and publish the chatflow, including welcome message and routing logic. Owner: marketing or ops.
3. Set availability rules and assignment logic so the right people get notified. Owner: support or sales manager.
4. Test across devices and SPA routes, confirming widget.refresh() fires correctly on navigation. Owner: developer or QA.
5. Confirm conversation logging and workflow triggers are firing into the correct contact records and sequences. Owner: sales or support lead.

Run through these five in order, and skip nothing, and you’ll have caught the failure points that generate the most “why isn’t chat working” tickets.

When HubSpot Chat Fits, and When It Doesn’t

HubSpot’s chat widget makes the most sense for teams already running their pipeline through HubSpot CRM. The value isn’t the widget itself, plenty of tools render a chat bubble competently, it’s that every conversation lands directly in a contact record your sales and support teams are already living in. If your team runs lean, centralizes its inbox in HubSpot, and mostly needs simple qualification bots rather than complex custom logic, this is close to the right default choice.

Where it gets more complicated is heavier custom logic or apps outside the standard web page model, particularly single-page apps with unusual routing, or products that need chat state synced with an entirely separate backend. That’s where the SDK’s throttling limits and refresh behavior deserve real attention before launch, not after.

For the setup side, some platform solutions handle the plumbing that usually eats a developer’s afternoon: dropping in tracking scripts, wiring up integrations, and keeping reusable components consistent across pages so your chat widget’s inline embed doesn’t break every time you update a landing page layout. That’s less about replacing HubSpot’s own tools and more about removing the manual work around them.

Get Your Chat Widget Live Without the Manual Setup Work

If you’ve read this far, you already know the HubSpot chat widget itself isn’t the hard part, wiring tracking codes, inline embed selectors, and SPA refresh logic into your actual site is. WebsitePublisher.ai closes that gap by letting you describe what you want in plain language and generating the site structure, integrations, and reusable components around it automatically, so a widget embed that would normally take a developer an afternoon takes a conversation instead.

Because WebsitePublisher.ai builds sites from reusable, data-driven components rather than static templates, updating your chat placement, swapping an inline embed for a floating launcher, or rolling a design change across every page happens once and propagates everywhere, instead of requiring a page-by-page rebuild. With numerous built-in integrations already available, adding a service like HubSpot alongside payments, email, or lead capture doesn’t require a separate developer sprint.

If you’re planning a new site or rebuilding an existing one around better lead capture, start with the AI website builder and see how quickly a chat-ready page comes together.

Official HubSpot Resources Worth Bookmarking

For the exact steps and API details straight from HubSpot, these are the pages worth keeping open in a tab:

• Create a live chat, the official Knowledge Base walkthrough for building your first chatflow from scratch.
• Connect and customize a chat channel, covering appearance, availability, and channel-level settings in more depth.
• Conversations Chat Widget SDK reference, the full developer documentation for methods, events, and configuration fields.
• Chat widget is not appearing on your pages, the dedicated troubleshooting guide for tracking code and cookie issues.
• HubSpot’s live chat product page, for a broader look at how chat fits into the wider CRM and support toolset.

Sources

• Create a live chat
• Engage Website Visitors with Free Live Chat | HubSpot

Recommended

• React on WebsitePublisher.ai — Deploy React Landing Pages by Conversation
• Build Websites with ChatGPT — ChatGPT AI Website Builder
• Build Websites with Claude — Claude AI Website Builder