Website widget

The website widget is Harriet's embedded chat for pages you control: your marketing site, product docs, or a public help center. Visitors ask questions without signing into Harriet, and you decide what Harriet knows and can do on that page.

How the widget works

The widget is a small chat panel, typically in the bottom corner of the page. Your site loads Harriet's embed script and calls HarrietChat.init with your customer id. Each widget you create in the console has a widget id; when your page sends a signed widgetId, Harriet merges in the defaults you saved for it: title, colors, position, initial message, suggested questions, instructions, and escalation routing.

When the page passes a widgetId, the widget itself runs in a frame served from your Harriet host, and your page loads only a small script that positions it. Your site's scripts and styles cannot change how the widget looks or behaves, and the rest of the page stays clickable around it.

Traffic is treated as a public session. Answers come only from the knowledge and skills you allow for that widget, not from the full private employee experience. If the visitor needs a person, Harriet can raise a ticket routed to the widget's escalation groups.

Create and configure a widget

1. Add the widget. Open Channels & embed → Surfaces and select Add website widget. Name it (for example "Marketing site") and select Create and configure. You land on the Public widget configuration page.
2. Scope its knowledge. On the Data and skills tab, tick Data groups (knowledge / documents). Checking a group adds this widget's public document id to the group's specialist channel list, which controls which knowledge Harriet can use for this widget. Publish only what is safe and useful on the open web.
3. Choose which skills answer. In the Skills (this widget) table, turn on only skills appropriate for unauthenticated visitors: product Q&A yes, "show my payslip" no.
4. Route escalations. On the Escalations tab, tick Escalation groups. Only groups with Ticket inbox enabled are listed. Point tickets at the right inbox: sales, support, or a partner desk.
5. Set instructions and the New case button. On the Customization tab, an optional Base prompt replaces Harriet's usual identity and instructions for this widget channel only. You can also show a "New case" button, a floating action above the chat panel, with an optional label and message prefix. The prefix is sent to Harriet and shown in the visitor's thread with their message. Optional card width and height (in pixels) set how big that card opens; leave them blank for the default size, and it shrinks to fit the screen.
6. Style it. On the Appearance tab, set the Preview title, Position (Bottom right or Bottom left), an optional Initial message (supports {userFirstName}), optional Suggested questions (one per line, up to six; they appear as buttons with the initial message, and clicking one sends that text as the visitor's message), and the Primary and Secondary colors. Open the case card ready to edit chooses how a new case card first appears: off shows the summary and an Edit link; on shows the form and Create Ticket. Match the page context so visitors know what the widget can answer.
7. Save and copy the embed. Select Save, then open the Embed snippet tab to copy your Widget ID and an example init for your pages.

Install the embed on your site

Load the CSS and JS from your Harriet host, then initialize. The Embed documentation page in the console shows this snippet with your real customer id and host filled in:

<link rel="stylesheet" href="https://YOUR_HARRIET_HOST/bots/embed/css/">
<script src="https://YOUR_HARRIET_HOST/bots/embed/js/"></script>
<script>
  HarrietChat.init({
    customerId: "YOUR_CUSTOMER_ID",
    apiUrl: "https://YOUR_HARRIET_HOST/bots/api/chat/",
    title: "Ask Harriet",
    position: "bottom-right",
    primaryColor: "#2622F7",
    secondaryColor: "#FFF2E2"
  });
</script>

To pin the page to a specific widget configuration, pass widgetId, timestamp, and a signature computed on your server. If you send widgetId, you must sign it; unsigned requests with widgetId are rejected. See Embed security for the canonical string and code examples.

You can also pass browserContext: up to 5 short strings (page title, product id, section name) sent with each message so Harriet knows where the visitor is. If the widget row in Harriet has non-empty browser context strings saved, those replace what the page sends.

Allow your site's origins

The widget only works on HTTPS pages whose hostnames you explicitly allow. Open Channels & embed → Browser origins and list the hosts, comma-separated: exact hosts such as www.example.com, or *.example.com for any subdomain. Apex domains must be listed explicitly; the wildcard does not include example.com. This stops other sites from loading your widget. Details in Embed security.

Sites with a Content Security Policy

If your site sends a Content-Security-Policy header, allow your Harriet host in frame-src (or child-src) as well as for the embed script and stylesheet. On Salesforce Experience Cloud, add your Harriet host as a CSP Trusted Site with frame-src enabled.

If the frame is blocked, the widget falls back to running directly in your page, which also needs your Harriet host in connect-src. The browser console then shows a warning that the widget frame did not load.

To run the widget directly in your page on purpose, pass embedMode: "page" in HarrietChat.init. Use it only when you cannot allow the frame: the widget then shares your page's styles and scripts, and some sites break parts of it.

If your page is itself shown inside another site's frame, such as an intranet portal or a Microsoft Teams tab, add that site's host to Browser origins too. Browsers check every frame around the widget, so a missing host makes the widget fall back to running in your page after a few seconds.

Styling and hiding the widget

Your site's CSS does not reach inside the widget's frame, so rules that targeted the widget's own elements no longer apply. To hide the widget on some pages, or to move it, target the frame's container instead, for example #jp-chat-widget-frame { display: none; }. Colors, position and the launcher are set in Appearance or in HarrietChat.init.

Conversations a visitor started before your site moved to the framed widget are not carried over; their next visit starts a new chat.

Test before launch

On the widget's configuration page, select Load preview to try the widget with your saved settings before touching your site. Once embedded, if the widget does not appear, confirm the page's hostname is on the origin allowlist, that your Content Security Policy allows the frame, and check the browser console for load errors. If answers cite no documents, check that your groups include the widget's public-… specialist entry. Signature errors usually mean the signed field set does not exactly match what the page sends.

See how the widget is helping

Open Team usage patterns and choose Embeddable chat widget. Each tab at the top shows one widget channel, or all of them together.

• Cases Harriet helped with first appears once the New case button is switched on. It shows how many visitors clicked New case in the last 30 days, how many went on to submit a case, and how many didn't need to. Of those who didn't, it shows how many Harriet answered and how many left without an answer, so you can tell real help apart from people giving up. The table underneath compares visitors who clicked New case with visitors who started by typing a question.
• How conversations ended shows every website conversation by month: answered by Harriet, left without an answer, passed to your team, or no question asked.

A conversation covers one topic. If a visitor comes back after a break of 4 hours or more, moves on to a new topic, or keeps chatting for over a day, it counts as a new conversation. Conversations appear in these charts within a few hours of finishing. New case results are counted from the day this report became available, so earlier conversations aren't included.

To read the conversations behind these charts, for example to find out what Harriet couldn't answer, analyze them in Harriet Desktop.