title: JavaScript API description: Control the Navigic widget programmatically with the NavigicWidget global. order: 3

JavaScript API

After the embed script loads, a NavigicWidget object is available on window. Use it to control the widget programmatically.

Setup

To use the API, load the script with data-manual="true" to prevent auto-initialization:

<script
  src="https://releases.navigic.ai/embed/embed.js?v=7"
  data-api-key="pk_wk_YOUR_KEY"
  data-manual="true"
  async
></script>

Then call init() when you're ready:

window.NavigicWidget.init({
  workspaceId: "pk_wk_YOUR_KEY",
  displayMode: "bubble",
  primaryColor: "#3e6d53",
  title: "Support",
  greeting: "How can we help?",
});

Methods

init(config)

Initialize the widget with the given configuration. Required when using data-manual="true".

NavigicWidget.init({
  workspaceId: "pk_wk_YOUR_KEY",  // required
  displayMode: "bubble",          // "bubble" | "panel" | "inline"
  position: "bottom-right",       // "bottom-right" | "bottom-left"
  primaryColor: "#2563eb",        // CSS color
  title: "Chat with us",          // header text
  greeting: "Hi! How can I help?",
  gatewayUrl: "https://navigic.ai/dashboard/runtime",
  panelWidth: "400px",            // panel mode only
  panelSide: "right",             // panel mode only
  targetElement: "#chat",         // inline mode only — CSS selector or HTMLElement
  mode: "live",                   // "live" | "mock"
});

destroy()

Unmount the widget, close the connection, and remove it from the DOM.

NavigicWidget.destroy();

open()

Open the chat window (bubble mode) or slide in the panel (panel mode).

NavigicWidget.open();

close()

Close the chat window or slide out the panel.

NavigicWidget.close();

identify(userId, traits?, auth?)

Link the current session to a known user. Use this after your user signs in.

NavigicWidget.identify(
  "user_123",                  // your internal user ID
  {
    email: "[email protected]", // optional traits
    name: "Jane Doe",
  },
  {
    userHash: "hmac_hex_here", // HMAC-SHA256 for verification
  },
);

See Identity Verification for how to compute the HMAC on your server.

Parameters:

NameTypeRequiredDescription
userIdstringYesYour internal user ID.
traitsobjectNoUser metadata — email, name, or any custom properties.
auth{ userHash?: string }NoHMAC hash for secure identity verification.

Behavior: Calling identify() disconnects the current session and reconnects with the new identity. The conversation history is preserved server-side.

reset()

Clear the identified user and revert to an anonymous session. Call this on logout.

NavigicWidget.reset();

Typical Integration

<script
  src="https://releases.navigic.ai/embed/embed.js?v=7"
  data-api-key="pk_wk_YOUR_KEY"
  data-manual="true"
  async
></script>
 
<script>
  // Wait for script to load
  document.querySelector('script[data-api-key]')
    .addEventListener('load', function () {
      // Initialize
      NavigicWidget.init({
        workspaceId: "pk_wk_YOUR_KEY",
        displayMode: "bubble",
      });
 
      // Close initially — open via your own button
      NavigicWidget.close();
    });
 
  // Your custom open button
  document.getElementById('help-btn')
    .addEventListener('click', function () {
      NavigicWidget.open();
    });
</script>