Integration Notes

Most integrations are boring: install, paste, ship. These are the details that matter for the 5% of cases where something looks weird or you want to understand what the SDK is doing.

CSS injection

The widget's CSS is bundled into dist/index.js as a runtime styleInject() call. The first time the widget mounts, it appends a <style> tag to document.head.

You do not need to import "@helpway/react/styles.css".

If your bundler is unusually aggressive about tree-shaking, the package is explicitly marked "sideEffects": true.

Visitor identity

Helpway tracks each visitor via two independent signals:

1. hw_visitor cookie — set server-side on first bootstrap, HttpOnly in production. Most reliable.
2. X-Visitor-Id header — derived from localStorage. Used as fallback when third-party cookies are blocked.

The server prefers the cookie when both are present.

Resetting identity

If you need to wipe the visitor (e.g., "Sign out" in your app):

import { clearVisitorId } from "@helpway/react";
 
function signOut() {
  clearVisitorId();
  document.cookie = "hw_visitor=; Path=/; Max-Age=0";
}

Clearing only one layer will not reset identity — the other layer will still resolve the old visitor.

Escalation loop prevention

The AI agent will never respond to its own messages. This is enforced at the decision layer — before the LLM is even called.

Grounding rules

The AI agent MUST consult the knowledge base before answering factual questions. If the KB doesn't contain the answer, the agent says so honestly and offers to connect a teammate — never invents a response.

Customers on a brand-new workspace (empty KB) will see the agent say "I don't have information about that. Would you like me to connect you with a team member?" — this is correct behavior, not a bug.

Local development

<HelpwayWidget apiKey="pk_test_xxx" apiUrl="http://localhost:52500" />