Widget

Outcome

Install the released Widget for one Agent, with the script tag on any site or the React package, and verify its exact allowed origin.

Prerequisites

• Active reviewed Knowledge and Public Chat.
• A manifest from the target Workspace and Agent.
• An exact HTTP(S) origin, and for React a client-only boundary.

Install and render

The App's Instalar page (Install in English) shows every snippet below with your Agent ID filled in.

Script tag

Any site, no framework. Paste the tag before </body> on every page that shows the Widget:

<script async src="https://app.andypartner.com/widget.js" data-andy-embed-id="<agent-id>" data-andy-api-url="https://app.andypartner.com/api"></script>

/widget.js always serves the release Andy currently supports, so the tag never needs a version.

React

andy widget manifest --workspace <workspace-id> --agent <agent-id-or-slug> --json
bun add andy-widget-react@2.3.2

Render AndyChat and pass the manifest's Agent ID as embedId. Pin the exact package version returned by the manifest; do not use latest or an iframe.

"use client";

import { AndyChat } from "andy-widget-react";

export function AndyWidget() {
  return <AndyChat embedId="<agent-id>" />;
}

Next.js

In the App Router the widget must live in a client component: it reads its configuration in the browser. Render the same pinned React package inside a client wrapper, then use the wrapper from a server layout or page.

// app/components/andy-widget.tsx — client wrapper
"use client";

import { AndyChat } from "andy-widget-react";

Object.assign(globalThis, { ANDY_CHAT_API_URL: "https://app.andypartner.com/api" });

export function AndyWidget() {
  return <AndyChat embedId="<agent-id>" />;
}

// app/layout.tsx (or any page) — server component
import { AndyWidget } from "./components/andy-widget";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <AndyWidget />
      </body>
    </html>
  );
}

Props

AndyChat (andy-widget-react@2.3.2) takes the Agent ID plus optional overrides. Every optional prop overrides the value from the Agent manifest; omit what you do not need to change.

Point the widget at your App API origin when the production default does not apply. The bundle reads window.ANDY_CHAT_API_URL first:

Object.assign(globalThis, { ANDY_CHAT_API_URL: "https://app.andypartner.com/api" });

Support

A Workspace with Soporte can give its own signed-in users Support Mode (My requests and Talk to the team) through the same Widget. Visitors who are not signed in keep the sales chat.

• Public ids only. The snippet carries the Agent ID and your Host Installation ID (Soporte › Configure). Never put a signing secret in a page.
• Your server signs the Requester Pass for the signed-in user, and getRequesterPass fetches it from your server. It throws when the pass is unavailable.
• Change contextKey on sign-in, sign-out and every company switch. Each change starts a fresh panel.

Sign the Requester Pass

Create a signing key for the Host Installation in Soporte › Configure. Andy shows its secret once: store it on your server only. For each signed-in user, your server returns an HS256 JWT with the key's kid in its header and these claims:

Andy refuses a pass with another algorithm, an unknown or retired key, a wrong issuer, Workspace or environment, or a longer lifetime.

With andy-widget-react@2.3.2, render the Support component for a signed-in user and the sales Widget otherwise:

import { AndyChat } from "andy-widget-react";

type User = { id: string; companyId: string };

export function AndyWidget({ user }: { user: User | null }) {
  if (!user) return <AndyChat embedId="<agent-id>" />;
  return (
    <AndyChat
      mode="support"
      support={{
        installationId: "<installation-id>",
        contextKey: `${user.id}:${user.companyId}`,
        getRequesterPass: async () => {
          const response = await fetch("/api/andy/requester-pass", { method: "POST", cache: "no-store" });
          if (!response.ok) throw new Error("Support authentication unavailable");
          return (await response.json()).pass;
        },
      }}
    />
  );
}

The script tag gains Support Mode with Widget 3.0, through AndyChat.configure({ agentId, support }), and there getRequesterPass returns null for a signed-out user. The Instalar page shows that form once /widget.js serves 3.0.

Configure the origin

andy widget configure --workspace <workspace-id> --agent <agent-id> --config ./widget.json --json
andy widget verify --workspace <workspace-id> --agent <agent-id> --origin https://example.com --json

Origins are exact scheme://host[:port] values. Paths, credentials, query strings, fragments, and wildcards are rejected.

Machine-readable verification

Require andy widget manifest ... --json to return the expected Agent, exact package/version, and configuration. Then require widget verify to report identity, origin, Knowledge, Public Chat, and answer checks as successful.

Reading these instructions never marks the channel connected. Andy reports the Website Widget as live only after the installed widget actually loads on your site from an allowed origin.

Next step

Connect the same catalog to an agent client through MCP.