Widget Runtime

The widget runtime powers customer-facing live chat. It uses widget public keys plus route-level controls rather than broad table access. Widget routes are not /api/v1 REST API endpoints and do not accept woesk_ workspace API keys.

Install Snippet

Use the install snippet from Settings → Channels → Live chat or Settings → Keys.

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

The public key can be a workspace widget key or an agent widget key. Agent keys route the conversation to that agent’s attached context.

Loader Behavior

https://woes.dev/widget.js is a small host-page loader. It fetches customer-safe widget configuration, records the install origin for operator verification, and mounts the real Woes product widget inside an isolated iframe at /embed/widget. The iframe resizes between launcher, teaser, and open-panel footprints so the host page does not need to reserve a fixed container. The loader forwards window.Woes(...) commands into the iframe once it is ready, and the iframe queues early commands until the inner widget API is installed. Early identify calls made during widget boot are not dropped. The config route returns presentation fields only: colors, logo URLs, welcome copy, quick links, pre-chat question labels, position, radius, theme, identity-required state, enabled surveys, published updates settings, business-hours fields, and enabled state. It does not return workspace settings, secrets, operator data, or API key material.

JavaScript API

The widget exposes a queued window.Woes(command, payload) API. Calls made after the snippet is added are queued until the widget runtime is ready.

Command	Payload	Result
`show`	none	Opens the messenger.
`hide`	none	Closes the messenger.
`open`	none	Alias for `show`.
`close`	none	Alias for `hide`.
`onShow`	callback or `null`	Runs a callback when the messenger opens. Pass `null` to remove it.
`onHide`	callback or `null`	Runs a callback when the messenger closes. Pass `null` to remove it.
`hideChatBubble`	none	Hides the launcher bubble.
`showChatBubble`	none	Shows the launcher bubble again.
`setTheme`	`"dark"`, `"light"`, `"system"`, or `"auto"`	Sets the widget theme behavior.
`onChangeUnreadMessagesCount`	callback or `null`	Receives unread-count changes.
`identify`	identity object	Connects the visitor to a customer identity.
`setNewConversationFields`	object	Adds metadata to the next new conversation.
`showNewMessage`	string	Opens the messenger with a draft message.
`showTicketForm`	form key	Opens a specific ticket form.
`setTicketFormFields`	object	Prefills ticket form fields.
`setVisibleTicketForms`	array or `null`	Restricts visible ticket forms. Pass `null` to reset.

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

window.Woes("onChangeUnreadMessagesCount", (count) => {
  console.log("Unread Woes messages", count);
});

Customer Identity

For unsigned installs, send the customer details you already know.

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. In HMAC mode, only the normalized email is verified; name, company, and id remain display metadata. Use JWT when account/contact ids must be verified.

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

For verified installs, pass either an HMAC email proof or a JWT minted by your backend. Verified identity should be fetched from an authenticated, no-store backend endpoint and retried after login/session load, widget load, focus, and visibility changes. See Widget Identity for the full security model.

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

window.Woes("identify", {
  jwt: identity.jwt,
});

Pre-chat Questions

Pre-chat questions are configured in Settings → Channels → Live chat and delivered through the widget config route. The widget asks them before the first message in a new conversation and shows the pre-chat form as the main new-chat pane while those details are needed. Required questions are enforced by the public message route, so a custom script cannot bypass them. If the page identifies a visitor with window.Woes("identify", ...), configured name, email, and company questions can be auto-filled from that identity. Verified identity modes should be used before trusting those fields for account-specific routing.

Conversation Metadata

Use conversation fields to attach page, product, account, or plan context to the next new conversation.

window.Woes("setNewConversationFields", {
  page: window.location.href,
  plan: "enterprise",
  account_id: "acct_123",
});

window.Woes("showNewMessage", "I hit a 401 on POST /orders.");

Conversation Continuity

A widget public key only resolves the workspace or agent. Continuing or reading an existing widget conversation also requires the opaque conversationSecret returned when the conversation is created. Store the secret per widget key in the browser, do not send it to analytics or logs, and prefer the x-widget-conversation-secret header for history requests. Public key plus conversation id alone must not be treated as authorization.

Ticket Forms

Ticket form commands let you open a specific form and control the customer-facing form choices.

window.Woes("showTicketForm", "bug_report");

window.Woes("setTicketFormFields", {
  subject: "Checkout error",
  priority_hint: "high",
});

window.Woes("setVisibleTicketForms", ["bug_report", "feature_request"]);
window.Woes("setVisibleTicketForms", null);

Resolve workspace or agent by widget key.
Create or continue a conversation.
Store customer messages.
Return customer-safe message history.
Emit widget events such as launcher view and widget open.
Update customer presence for active visitors.
Submit CSAT or NPS survey responses.
Show published updates and track verified-reader read state.

Public Boundaries

Widget responses must not include:

Operator-only debug traces.
Provider or model internals.
Raw secrets.
Another workspace’s data.
Service-role information.

Route family	Purpose
`/api/widget/config`	Public widget presentation config for a workspace or agent key.
`/api/widget/identity`	HMAC/JWT identity proof verification.
`/api/widget/messages`	Customer message flow and conversation history.
`/api/widget/events`	Widget impressions, opens, closes, and engagement events.
`/api/widget/presence`	Customer presence heartbeat.
`/api/widget/feedback`	Customer-safe message feedback state for a verified widget conversation.
`/api/widget/csat`	Compatibility route for CSAT and NPS widget survey responses.
`/api/widget/updates`	Published widget updates.
`/api/widget/updates/read`	Verified-reader update read state.

The /api/widget/csat route name is kept for compatibility, but it can record typed survey responses when the survey is configured as CSAT or NPS.

Use Widget Routes for route-by-route request requirements and boundary details.

API reference

Widget Runtime

Widget Runtime

Install Snippet

Loader Behavior

JavaScript API

Customer Identity

Pre-chat Questions

Conversation Metadata

Conversation Continuity

Ticket Forms

Public Widget Capabilities

Public Boundaries

Common Widget Routes

​Widget Runtime

​Install Snippet

​Loader Behavior

​JavaScript API

​Customer Identity

​Pre-chat Questions

​Conversation Metadata

​Conversation Continuity

​Ticket Forms

​Public Widget Capabilities

​Public Boundaries

​Common Widget Routes

Widget Runtime

Install Snippet

Loader Behavior

JavaScript API

Customer Identity

Pre-chat Questions

Conversation Metadata

Conversation Continuity

Ticket Forms

Public Widget Capabilities

Public Boundaries

Common Widget Routes