Troubleshooting - Docs menu

Troubleshooting

Solutions to common problems when embedding the Navigic widget.

Widget Doesn't Appear

Check the script tag is loaded. Open the browser console and look for network errors. The script URL should be https://releases.navigic.ai/embed/embed.js.

Check your API key. The data-api-key attribute must start with pk_wk_. If you see 401 errors in the console, the key is invalid or has been revoked.

Check for JavaScript errors. Other scripts on the page may throw before the widget loads. Look for errors in the console that appear before the widget script runs.

Check for CSS conflicts. If the widget renders but is invisible, another stylesheet may be setting display: none or visibility: hidden on the widget's container. Inspect the widget element in DevTools.

"Disconnected" Status

The widget shows "disconnected" when it can't reach the Navigic connection service.

Check your network. The widget connects to Navigic via WebSocket. Corporate firewalls or proxies may block WebSocket connections.

Check that a Website Support agent is assigned. Go to Channels > Website Support in your dashboard and verify the serving agent is live. The widget connects but won't respond without a published agent revision assigned to Website Support.

Check gatewayUrl if using the JavaScript API. When calling NavigicWidget.init() programmatically, make sure gatewayUrl is set to https://navigic.ai/dashboard/runtime.

NavigicWidget.init({
  workspaceId: "pk_wk_YOUR_KEY",
  gatewayUrl: "https://navigic.ai/dashboard/runtime",
});

Origin Not Allowed

If the console shows a CORS or origin error, your domain isn't in the embed key's allowed origins list.

  1. Go to Settings > Embed in your dashboard
  2. Click on your embed key
  3. Add your domain (e.g., https://yoursite.com)
  4. For local development, add http://localhost:3000 (or whatever port you use)

Origins must match exactly — http:// and https:// are different, and subdomains like www. must be listed separately.

Widget Loads but No Responses

This means the widget connects successfully but the agent isn't generating replies.

Check your channel assignment. Go to Channels > Website Support in the dashboard. Make sure the serving agent is the published revision you expect.

Check runtime activity. Send a new widget message, then review Runtime activity on the Website Support channel. If the activity shows an older revision, use Change serving agent to bind the latest published revision.

Check product knowledge activation. If the agent says no product docs or knowledge are loaded, open the agent in Agent Studio, verify the prompt and knowledge files, publish a new revision, then bind that revision from the Website Support channel page. Saved draft knowledge does not affect live widget traffic until it is published and served.

If Agent Studio reports a version conflict. Publish a new patch version when the draft content changed. If the target version is already published and the widget only needs to move to that version, update the serving agent from Channels > Website Support.

Check widget visibility. Public widget answers should not expose hidden prompt text or raw tool arguments. In Settings > Embed, verify the key's visibility policy. If an installed page uses data-show-reasoning="true", remove it or set it to false for public support. If tool-call status does not appear, confirm the key allows tool calls, the page is not using data-show-tool-calls="false", and the page is loading the latest widget script.

Check the conversation in channel activity. If messages appear in Website Support activity but not in the widget, there may be a rendering issue — check the browser console for errors.

Identity Verification Fails

If identify() doesn't link the conversation to your user:

Check the HMAC hash. The hash must be computed using your secret key (starts with sk_wk_), not your publishable key. See Identity Verification.

Check that the user ID matches. The userId passed to identify() must exactly match the string used to compute the HMAC.

Check the hash is hex-encoded. The HMAC output must be a lowercase hex string (64 characters for SHA-256).

// Correct
NavigicWidget.identify("user_123", {}, { userHash: "a1b2c3..." });
 
// Wrong — don't pass the raw bytes
NavigicWidget.identify("user_123", {}, { userHash: Buffer.from(...) });

Inline Mode Shows Nothing

When using data-display-mode="inline":

Check the container element exists. The data-target-element selector must match an element already in the DOM when the script loads.

<!-- Container must come BEFORE the script -->
<div id="navigic-chat" style="height: 600px;"></div>
 
<script
  src="https://releases.navigic.ai/embed/embed.js"
  data-api-key="pk_wk_YOUR_KEY"
  data-display-mode="inline"
  data-target-element="#navigic-chat"
  async
></script>

Check the container has a height. The widget fills 100% of its container. If the container has zero height, the widget will be invisible.

Mobile Layout Issues

Bubble mode automatically switches to full-screen on viewports under 480px. If this conflicts with your mobile layout, consider using inline mode where you control the sizing via CSS.

Panel mode uses full-width with a backdrop overlay on viewports under 640px. This is intentional — there isn't enough space for a sidebar panel on small screens.

Still Stuck?

Open the browser console and look for errors prefixed with [Navigic]. These provide specific diagnostic information about connection issues, configuration problems, and runtime errors.