Install the Widget

The Woes widget lets customers ask questions from your product or docs site. Public widget access uses a workspace or agent widget key; it does not grant general account access.

Key	When to use it
Workspace widget key	The default workspace agent and one shared install path.
Agent widget key	Different agents on different websites, products, docs areas, or customer segments.

Find widget keys in Settings → Keys. Agent widget keys also appear with each agent in Agents.

Basic Install

Add the Woes snippet to the pages where customers should be able to ask for help.

<script
  src="https://woes.dev/widget.js"
  data-public-key="YOUR_WIDGET_PUBLIC_KEY">
</script>

Use the actual snippet from Settings → Channels → Live chat because production script URLs and options may vary by workspace.

The widget exposes a queued browser API, so you can call window.Woes(...) after the snippet is present on the page.

window.Woes("show");
window.Woes("hide");
window.Woes("setTheme", "dark");

Documentation Sites

If your docs are hosted on Mintlify, install Woes with a root-level JavaScript file in the Mintlify content directory. See Install the Widget in Mintlify.

Identify Customers

For signed-in products, identify the customer so conversations are tied to a stable account.

Unsigned identify fields are display and routing metadata, not authentication. Any browser user can alter them. Use HMAC or JWT identity verification before showing account-specific history or trusting account/customer ids.

window.Woes("identify", {
  email: "ada@example.com",
  name: "Ada Lovelace",
  company: "Example API Co",
  id: "user_123",
});

For higher-trust installs, use Widget Identity with HMAC email verification or JWT. Configure it from Settings → Security after selecting the agent widget key installed on this site. Verified identity should be generated only by your backend. Store the public widget key in browser-safe config and store the identity secret only in server-side environment variables.

Value	Where it belongs
`WOES_AGENT_WIDGET_PUBLIC_KEY`	Browser-safe config used as `data-public-key`.
`WOES_WIDGET_IDENTITY_SECRET`	Server-only signing secret copied from Settings → Security.

Your backend should expose an authenticated, no-store identity endpoint, such as /api/woes-identity, that returns { id, email, email_hash, name, company } for HMAC mode or { jwt } for JWT mode. Browser code should fetch that endpoint after login/session load, when widget.js loads, on window focus, and when the page becomes visible again. Calling window.Woes("identify", ...) repeatedly for the same signed-in user is safe and prevents boot-order races from leaving the customer anonymous. The selected agent matters. The data-public-key in the script tag must match the agent selected in Settings → Security, and the backend proof must be generated with that same agent’s identity secret.

window.Woes("identify", {
  id: identity.id,
  email: identity.email,
  email_hash: identity.email_hash,
  name: identity.name,
  company: identity.company,
});

Generate identity proofs only on your backend. Never ship the widget identity secret to the browser, logs, analytics tools, or customer-visible pages.

Verify the Install

After adding the snippet, use Woes to confirm the site is wired correctly:

Open Settings → Security.
Select the agent widget key used by the installed snippet.
Load the page where the widget is installed.
Click Refresh in Install check and confirm the site origin appears.
Generate a real HMAC hash or JWT from your backend.
Paste it into Test an identity proof and click Verify proof.
Send a test widget message as a logged-in user and confirm Woes shows email/name with identity_source of widget-token.

If the widget appears but the conversation is still anonymous, the most common cause is missing server-side identity configuration or a mismatch between the installed data-public-key, the selected agent in Woes, and the identity secret used by the backend.

Common JavaScript Calls

Call	Use it for
`window.Woes("show")`	Open the messenger.
`window.Woes("hide")`	Close the messenger.
`window.Woes("hideChatBubble")`	Hide the launcher bubble.
`window.Woes("showChatBubble")`	Show the launcher bubble again.
`window.Woes("setTheme", "dark")`	Switch the widget theme. Use `"light"` for light mode.
`window.Woes("showNewMessage", text)`	Open the widget with a draft message.
`window.Woes("setNewConversationFields", fields)`	Prefill metadata for the next conversation.

Existing conversation history for the verified customer.
Agent replies grounded in attached API context.
Operator replies after takeover.
Delivery, unread, typing, and closed-conversation states.
Published updates when the Updates tab is enabled.
CSAT or NPS surveys after supported resolution events.

Common Checks

Symptom	Check
Widget does not load	Confirm the public key and script URL.
Conversation is anonymous	Confirm the signed identity endpoint exists, the server-only secret is configured, and identify is retried after widget/auth lifecycle events.
Agent answers from the wrong context	Use the right agent widget key and verify source attachments.
Updates do not appear	Confirm published updates exist and the widget Updates tab is enabled.
Survey does not appear	Confirm the survey is enabled, uses a widget channel, and triggers on issue solved.

Woes documentation

Install the Widget

Install the Widget

Choose A Widget Key

Basic Install

Documentation Sites

Identify Customers

Verify the Install

Common JavaScript Calls

What The Widget Can Show

Common Checks

​Install the Widget

​Choose A Widget Key

​Basic Install

​Documentation Sites

​Identify Customers

​Verify the Install

​Common JavaScript Calls

​What The Widget Can Show

​Common Checks

​Related Pages

Install the Widget

Choose A Widget Key

Basic Install

Documentation Sites

Identify Customers

Verify the Install

Common JavaScript Calls

What The Widget Can Show

Common Checks

Related Pages