Whater.ai Widget Developer Guide

This guide explains how to embed the Whater.ai chat widget, customize its behavior, and inject rich customer context from your host application.

1. Quick Start

Add the widget custom element and script bundle to any page that can load standard HTML:

<body>
  <!-- Other page content -->

  <whater-chat-widget
    flow-id="YOUR_FLOW_ID"
    org-id="YOUR_ORG_ID"
    position="bottom-right"
    show-pre-chat-form="true"
    theme-primary-color="#0F62FE"
  ></whater-chat-widget>

  <script
    src="https://whater.ai/whater-chat-widget.bundle.js"
    async
    defer
  ></script>
</body>

Tip: Load the script once per page. Multiple <whater-chat-widget> instances can coexist after the script registers the custom element.

2. Required Configuration

Attribute	Required	Description
`flow-id`	Yes	Chat flow to load. Provided in the Whater.ai console.
`org-id`	Yes	Organization identifier issued by Whater.ai.
`position`	No	`bottom-right`, `bottom-left`, `side-right`, `side-left`, or `inline`. Defaults to `bottom-right`.
`is-open`	No	`true` to render expanded on load. Default `false`.
`show-pre-chat-form`	No	`true` to collect lead data before the chat.
`show-whatsapp-button`	No	`true` renders a "Continue on WhatsApp" CTA.
`suggested-questions`	No	Pipe-separated list of quick replies.
`default-country-code`	No	Overrides the WhatsApp and phone defaults. Falls back to `+91`.
`theme-primary-color`	No	Hex color that drives buttons, accents, and launcher.
`theme-primary-foreground-color`	No	Hex color for text/icons that sit on the primary color.
`theme-font-family`	No	CSS font stack for the chat surface.
`session-context`	No	JSON string or URI-encoded JSON with session metadata.
`default-message-context`	No	JSON string merged into every outbound user message.

When providing JSON via attributes, either escape quotes (") or URI-encode the string to avoid HTML parsing issues.

3. Loading the Bundle

Host the bundle from the Whater.ai CDN (recommended) or serve public/whater-chat-widget.bundle.js from your own infrastructure.
Use async defer to avoid blocking rendering.
For single-page apps, ensure the <script> tag stays in the main document so route transitions do not unregister the custom element.

4. Static Context Injection

You can seed session and message context statically via attributes. Both accept raw JSON or URI-encoded strings.

<whater-chat-widget
  flow-id="..."
  org-id="..."
  session-context='{"tenant":"dealer-ny","campaign":"launch"}'
  default-message-context='{"page":{"model":"CX-7","color":"pearl"}}'
></whater-chat-widget>

session-context becomes part of the payload and is synced to Whater.ai generated artifacts under injected_context in APIs or visible in the UI.
default-message-context merges into each user message written to Whater.ai.

5. Dynamic Context APIs

Once the element is connected, the host page can call imperative APIs on the element instance. These APIs accept plain JavaScript objects. Use them to keep data in sync with in-page events.

const widget = document.querySelector('whater-chat-widget');

widget?.setSessionContext({
  tenant: 'dealer-42',
  campaign: 'holiday',
}, { merge: true });

widget?.setDefaultMessageContext({
  page: { model: selectedModel, color: selectedColor },
}, { merge: true });

widget?.setNextMessageContext({
  lead_source: 'hero-cta',
});

Available methods:

setSessionContext(context, options?)
clearSessionContext(keys?)
getSessionContext()
setDefaultMessageContext(context, options?)
clearDefaultMessageContext(keys?)
getDefaultMessageContext()
setNextMessageContext(context)
clearNextMessageContext()
getNextMessageContext()

options.merge (default false) performs a shallow merge, letting you overwrite only the keys you supply.

6. React Example (Single Page Apps)

Use a ref to the Web Component to call the APIs from React components.

import { useEffect, useRef } from 'react';

type WidgetElement = HTMLElement & {
  setSessionContext: (ctx: Record<string, unknown>, options?: { merge?: boolean }) => void;
  setDefaultMessageContext: (ctx: Record<string, unknown>, options?: { merge?: boolean }) => void;
};

export function VehicleWidgetBridge({ model, color }: { model: string; color: string }) {
  const widgetRef = useRef<WidgetElement | null>(null);

  useEffect(() => {
    if (!widgetRef.current) return;

    widgetRef.current.setSessionContext({
      tenant: 'dealer-42',
      journey_stage: 'build-and-price',
    }, { merge: true });

    widgetRef.current.setDefaultMessageContext({
      page: { model, color },
    }, { merge: true });
  }, [model, color]);

  return (
    <whater-chat-widget
      ref={widgetRef as unknown as React.RefObject<any>}
      flow-id="YOUR_FLOW_ID"
      org-id="YOUR_ORG_ID"
      position="bottom-right"
      show-pre-chat-form="true"
    ></whater-chat-widget>
  );
}

7. Theming and Layout Controls

Use position="side-right" or position="side-left" to dock the widget to the viewport edge while keeping the launcher accessible.
Set position="inline" to mount the widget inside existing layouts such as sidebars or help centers. Pair with CSS:
```
whater-chat-widget[position="inline"] {
  display: block;
  min-height: 540px;
}
```
Override launcher/button colors via theme-primary-color and supporting contrast through theme-primary-foreground-color.
Supply brand typography with theme-font-family (it applies inside the shadow DOM without affecting the host page).

8. Pre-Chat Form and Lead Capture

Enable show-pre-chat-form="true" to collect name, email, phone, or custom fields before the session starts.
The widget automatically merges collected lead information into both session and default message context, ensuring downstream automations receive the same data.
Configure required fields and copy in the Whater.ai console.

9. WhatsApp Handoff

Toggle show-whatsapp-button="true" to display a WhatsApp CTA inside the chat footer.
Combine with context injection to pass wa_campaign or wa_thread_id to downstream analytics when the CTA is used.

10. Password Protection (Optional)

For demos or staged rollouts, enable password protection in the Whater.ai dashboard. If a password is present in the retrieved configuration, the widget renders a password gate before loading the chat.

11. Implementation Checklist

Fetch flow-id and org-id from the Whater.ai console.
Decide on position and container layout.
Add the <whater-chat-widget> element and script tag to your page shell.
Configure required attributes (pre-chat form, theming, WhatsApp, suggestions).
Seed session-context and default-message-context statically or dynamically.
Hook host page events into the dynamic context APIs.
Validate session creation and message context availability in Whater.ai dashboard.
Test both desktop and mobile launcher behavior.
Roll out behind a feature flag if deploying to production user flows.

12. Troubleshooting

Symptom	Check
Widget never appears	Confirm the script is loading (no 404) and that the custom element exists in the DOM.
Stuck on loading	Verify the flow-id and org-id from the console.
Session context missing	Inspect the session data in Whater.ai app to confirm updates.
Attributes ignored	Ensure attribute names use kebab-case, and JSON values are valid/encoded.

Embed and customize the Whater.ai chat widget

Widget playground

Live playground

Embed in minutes

Brand the experience

Personalize with context