Get started

Webchat Embed Reference

The webchat embed code, its config options, the browser API, and the public config the widget loads.

Webchat Embed Reference#

The webchat is added to a website with a small loader script, widget.js, configured through window.HayChat.config. The loader draws the chat button, fetches the organization's public webchat config, and downloads the rest of the chat when it is needed. Merchants get a ready-made snippet from Channels → Webchat → Install in the dashboard (see the Webchat user guide).

Source of truth: webchat/src/types/index.ts (HayChatConfig, PublicConfig) and server/services/webchat/webchat-settings.service.ts (getPublicConfig).

The snippet#

<script>
  window.HayChat = window.HayChat || {};
  window.HayChat.config = {
    organizationId: "YOUR_ORG_ID",
    baseUrl: "https://hay.example.com",
  };
</script>
<script src="https://hay.example.com/v1/webchat/widget.js" async></script>

baseUrl is the Hay server URL; widget.js is served from {baseUrl}/v1/webchat/widget.js. Place the snippet before </body> on every page.

Precedence#

Most options are also set in the dashboard. A value given in the embed config wins over the dashboard value; leave an option out to use the dashboard's. The dashboard snippet sets only organizationId and baseUrl, so every dashboard change reaches the site without updating the code.

Config options#

Option Type Default Description
organizationId string required The organization the chat belongs to.
baseUrl string required Hay server URL.
widgetTitle string dashboard Chat title, else "Chat with us" Header title when the assistant has no name.
position "left" | "right" dashboard Button position, else "right" Corner of the chat button.
brandColor string ("#rrggbb") dashboard Brand colour, else "#001df5" Any hex colour. The widget derives readable text and accent colours from it; the button keeps the exact colour.
themeMode "light" | "dark" | "system" dashboard Theme, else "light" "system" follows the visitor's prefers-color-scheme (shown as Match the visitor in the dashboard).
logoUrl string dashboard logo Logo shown in the header and on the home view.
homeHeading string dashboard Heading Heading of the home view.
showGreeting boolean dashboard, else true Start new conversations with the greeting message.
greetingMessage string dashboard Greeting The greeting text.
teaserMessage string dashboard Message next to the chat button Short message beside the closed button until the visitor opens the chat or dismisses it. "" shows none on this page. With loading: "interaction" only a message given here shows.
csatEnabled boolean dashboard, else true Ask for a 1–5 rating (five faces) when a conversation ends.
csatQuestion string dashboard, else "How did we do?" Question above the rating.
context Record<string, unknown> — Public context for the AI prompt. See the Context API.
customerExternalId string — Your system's ID for a signed-in user. Only used together with a valid signature.
customerExternalIdSignature string — Hex HMAC-SHA256 of customerExternalId, keyed with the organization's identity secret (Install → Signed-in customers). Compute it on your server.
locale string browser language Widget UI language, e.g. "en-us", "pt-br", "fr-fr".
consent "strict" | "implicit" "implicit" Device storage consent. "implicit" enables persistent storage once the visitor sends their first message; "strict" waits for HayChat.grantConsent(). Nothing is stored before the first message in either mode.
loading "eager" | "idle" | "interaction" "idle" When the chat (everything but the button) is downloaded. "interaction" fetches nothing, not even the public config, until the visitor reaches for the button, so the button paints in brandColor or the default until then.
onConversationStarted (conversation: { id: string }) => void | Promise<void> — Called when the first message creates a conversation. If it returns a Promise, that first message is sent once it resolves.
debug boolean false Log widget diagnostics to the browser console.

Removed: theme (the four colour presets) and widgetSubtitle. Use brandColor and themeMode; the header's second line now comes from the organization's availability ("Typically replies in …").

Browser API#

Available on window.HayChat once widget.js has run (calls made before the chat chunk loads are queued and replayed in order):

Method Description
addContext(key, value) Add or update public context (see the Context API).
grantConsent() / revokeConsent() Give or withdraw consent for device storage, e.g. from a cookie banner. Revoking wipes persistent hay-* storage.
setTeaserMessage(message) Show or replace the message next to the button; "" removes it.
registerTool(tool) / unregisterTool(name) Register a page tool (WebMCP shape) the AI may call in this browser. Needs Allow page actions in the dashboard.
highlight(target, label?) Draw the AI highlight around an element while a page tool acts on it.

Device storage consent also gates the visitor's conversation history: the home view's Your conversations list is only fetched after consent.

Public config#

On load the widget fetches webchat.getPublicConfig for the organization. It carries no secrets:

Field Description
enabled false when the chat is switched off or the organization is suspended; the loader removes the button.
widgetTitle, position From the dashboard.
brandColor Hex #rrggbb. Imported from the organization website's icon unless the merchant picked one.
themeMode "light", "dark" or "system".
logoUrl The webchat logo, else the organization logo, else null (the widget shows the organization's initial).
homeHeading Home view heading; null means the localized "How can we help?".
team Up to two { firstName, avatarUrl } of people who can take over; [] when handoff is off.
organizationName The organization display name, shown as "Support team · {name}" while a person has taken over.
showGreeting, greetingMessage, teaserMessage From the Content tab.
csatEnabled, csatQuestion End-of-chat rating.
agentName, agentAvatarUrl The assistant identity.
aiLabelShown, aiLabelText The AI label next to the assistant's name (set in Customer Privacy).
preChatForm The pre-chat form schema, or null.
contributions Declarative plugin contributions the widget supports (for example a bot challenge). Never code.

organizationLogoUrl, theme and widgetSubtitle are no longer returned.

The public config request also records install detection: while the chat is switched on, the request's Origin (or Referer) and time are stored as the webchat's last-seen site and time, at most once a minute per organization and only for sites in the Allowed websites list. The dashboard shows them as Working · Seen on {host} {time}. Requests with Origin: null (such as the dashboard's sandboxed preview) are ignored.

Live updates in the widget#

Besides messages, the conversation socket sends the widget:

Frame Meaning
{ type: "message_ack", messageId, clientMessageId?, status: "received" | "delivered" } A visitor message was stored (one tick), then picked up by the AI or queued for the team (two ticks).
{ type: "message_read", messageId, readAt } A person opened the conversation in the inbox (shown as Seen). Not sent for the AI and not stored.
{ type: "agent_activity", state: "start" | "end", toolName, label, doneLabel } The AI started or finished a tool. label / doneLabel come from the tool definition (plugin tool progress labels), else "Working on it…" / "Done".

AI messages carry metadata.sources ({ title, url }[], only documents with a public URL; absent when none). Human agent messages and join/leave notices carry metadata.agentAvatarUrl.

Visitors rate an AI answer with publicConversations.rateMessage({ conversationId, messageId, rating: "up" | "down", proof }). Only sent AI answers of the visitor's own conversation can be rated, and rating again replaces the earlier rating. Ratings are stored as message feedback with source visitor (good / bad) and show in Feedback Insights. publicConversations.listMine returns the visitor's recent conversations (max 20, newest first) for the home view, only after consent.

Last updated November 12, 2026

View on GitHub