Widget in your app

Put the Nevox agent inside your website, app or customer portal, with the user already identified.

The widget is the fastest way to put the agent in your interface. It uses the same agent and the same knowledge as the other channels.

Anonymous visitor (public website)

Paste before </body>:

html

<script
  src="https://nevox.ai/widget.js"
  data-key="nvx_pk_live_..."
  data-agent="agt_8f2k1x"
  async
></script>

Logged-in user (app, customer portal, admin)

Your server generates a session token for the logged-in user.
The front end passes that token to the widget.

html

<script
  src="https://nevox.ai/widget.js"
  data-key="nvx_pk_live_..."
  data-agent="agt_8f2k1x"
  data-session-token="nvx_st_9c1e..."
  async
></script>

With the token, the agent:

greets the person by name and replies in the contact's language;
continues that contact's same widget conversation, on any device;
can call actions with their external_id (e.g. fetch upcoming appointments).

The token is valid for 1 hour. When it expires, the widget tells you through the session_expired event: generate a new one on your server and call Nevox.setSessionToken.

In React, Next.js or Capacitor apps

tsx

"use client";
import { useEffect } from "react";

export function NevoxSupport({ sessionToken }: { sessionToken: string }) {
  useEffect(() => {
    const s = document.createElement("script");
    s.src = "https://nevox.ai/widget.js";
    s.async = true;
    s.dataset.key = process.env.NEXT_PUBLIC_NEVOX_KEY!;
    s.dataset.agent = "agt_8f2k1x";
    s.dataset.sessionToken = sessionToken;
    document.body.appendChild(s);
    return () => {
      window.Nevox?.destroy();
      s.remove();
    };
  }, [sessionToken]);

  return null;
}

In Capacitor or WebView apps, the widget works the same way inside the WebView.

Options

Attribute	Default	Description
`data-key`	—	Publishable key. Required.
`data-agent`	—	Agent ID. Required.
`data-session-token`	—	Session token for the logged-in user
`data-mode`	`bubble`	`bubble` (floating button) or `inline` (inside an element)
`data-target`	—	CSS selector of the element, when `data-mode="inline"`
`data-language`	the contact's or the account's	`pt-BR` or `en-US` (`es` coming soon)
`data-position`	`right`	`right` or `left`
`data-open`	`false`	Opens the chat as soon as the page loads
`data-track`	`true`	Turns on visitor tracking
`data-consent`	`auto`	`auto`, `required` or `granted`. See consent.
`data-widget`	`true`	`false` measures visits without showing the chat

Colors, name and logo are the ones from your website chat, configured in the dashboard (Channels → Website chat) and applied automatically. The publishable key and the allowed domains are in Dashboard → Developers → Widget in your app, with ready-to-paste code.

Without data-session-token, the conversation belongs to an anonymous visitor (one per browser), with a daily message limit to prevent abuse. Widget conversations show up in Conversations in the dashboard and count toward the plan's conversation allowance.

JavaScript API

Once the script loads, the window.Nevox object is available:

Nevox.open();                       // opens the chat
Nevox.close();                      // closes the chat
Nevox.send("I want to reschedule"); // sends a message as the user
Nevox.setSessionToken("nvx_st_..."); // swaps the token (e.g. after renewing it)
Nevox.identify("patient_1042", { name: "Mary Smith" }); // links the visitor to a contact
Nevox.track("plan_viewed", { plan: "family" });         // custom event
Nevox.consent("granted");           // records tracking consent
Nevox.destroy();                    // removes the widget from the page

Nevox.on("ready", () => {});
Nevox.on("open", () => {});
Nevox.on("message", (msg) => {});          // { role, content }
Nevox.on("handoff", () => {});              // the conversation was handed off to your team
Nevox.on("session_expired", async () => {
  const { token } = await fetch("/api/nevox-token").then((r) => r.json());
  Nevox.setSessionToken(token);
});

Security: Nevox.identify on the front end only links the visitor to a contact for analytics. It does not grant access to the contact's history. For the agent to see the user's data, always use the session token generated on the server.

Use the widget when	Use the conversations API when
You want a ready-made chat, with the look configured in the dashboard	You want an interface that's 100% yours
You need to go live quickly	The chat is part of a larger screen in your system
The user talks directly to the agent	Your server sits between the user and the agent