Embed Chat Widget

Drop your AVCodex agent onto any web page: a customer support portal, an integrator's client microsite, an internal tech-services dashboard, or the QR-code landing page taped inside a conference room.

Two embed options. Pick the one that fits your layout.

The chat widget adds a floating chat bubble to the corner of any page. Click it and your AVCodex agent opens in an overlay. It's lightweight (~5KB gzipped), uses Shadow DOM for CSS isolation, and runs on any site (WordPress, Webflow, an integrator's marketing page, an internal SharePoint page, a Q-SYS web UI).

Quick Start#

Add a single <script> tag before the closing </body> tag on your site:

<script src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"></script>

That's it. The widget auto-detects your agent from the subdomain and renders a floating chat bubble in the bottom-right corner.

Getting the Widget Code#

1. Open Share Settings

In your AVCodex agent, click Publish > Share in the navigation.

2. Find the Widget Card

Look for the Widget card on the Share page.

3. Copy the Code

Click the code snippet to copy it to your clipboard:

<script src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"></script>

4. Add to Your Site

Paste the code before the closing </body> tag.

Customizing with Data Attributes#

Customize the widget with data-* attributes on the script tag:

<script
  src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"
  data-position="bottom-left"
  data-greeting="Need a hand with the room?"
  data-greeting-delay="3000"
  data-color="#0E5C66"
  data-bubble-size="64"
></script>

#### Attribute Reference

#### Config Priority

Data attributes win. If you set a value via data-*, it overrides server-side configuration. Full priority order:

1. Data attributes on the <script> tag (highest)
2. Builder widget config (saved in the Widget tab)
3. Agent brand styles (logo, primary color)
4. Defaults (lowest)

Configuring in the Builder#

You can also configure the widget visually in the Builder:

1. Open your agent in the Builder
2. Go to Publish > Widget
3. Adjust position, size, greeting, and other settings
4. See changes reflected in the live preview
5. Changes save automatically and update the widget in real time

The Builder Widget tab covers the same options as data attributes, plus a live preview showing how the widget will look on the host site.

Widget Features#

• CSS isolation: Uses Shadow DOM, so your site's CSS won't fight the widget and vice versa.
• Instant open: Preloads the chat iframe on hover, so it opens immediately when clicked.
• Greeting bubble: Optional animated preview message to encourage interaction (good for end-user QR-code support pages).
• Responsive: Full-screen overlay on mobile, positioned popup on desktop.
• Accessible: Full keyboard navigation, ARIA labels, focus management, reduced-motion support.
• Lightweight: ~5KB gzipped (versus 42KB for the legacy widget).

The widget exposes a window.AVCodexWidget API for programmatic control. Use it to open and close the chat, identify users, and listen for events from your own JavaScript.

Basic Controls#

// Open the chat
AVCodexWidget.open();

// Close the chat
AVCodexWidget.close();

// Toggle open/closed
AVCodexWidget.toggle();

// Check if chat is open
if (AVCodexWidget.isOpen()) {
  console.log("Chat is open");
}

// Remove the widget completely (cannot be undone)
AVCodexWidget.destroy();

User Identification#

Identify users so chat history persists across sessions and you can see who's chatting in your dashboard. Useful when the agent is sitting on a logged-in integrator portal or a tech-services console.

#### Client-Side (Simple)

Pass the user's email and optional name directly. Simplest path for sites where the chat doesn't require authentication, like a public room-support page reached by QR code:

AVCodexWidget.setUser({
  email: "tech@integrator.example",
  name: "Field Tech"
});

#### Server-Side (Secure)

For agents with authentication enabled, use server-side token generation to verify the user's identity from your backend. Prevents spoofing.

Step 1: Generate a token on your server

Call the Builder API from your backend to get a bearer token:

curl -X POST https://your-agent.app.avcodex.com/api/v1/apps/{APP_ID}/consumers/auth \
  -H "Authorization: Bearer YOUR_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "programmer@integrator.example", "name": "Lead Programmer"}'

Response:

{
  "data": {
    "token": "eyJhbGciOi...",
    "consumer": {
      "id": "...",
      "email": "programmer@integrator.example",
      "name": "Lead Programmer"
    }
  }
}

Step 2: Pass the token to the widget

Send the token to your frontend and pass it to setUser:

AVCodexWidget.setUser({
  email: "programmer@integrator.example",
  name: "Lead Programmer",
  token: "eyJhbGciOi..."  // Bearer token from your server
});

The token authenticates the chat session inside the iframe without cookies, which keeps things working in cross-origin embeds (an integrator portal hosting an AVCodex agent on a different domain).

Note: You need a Builder API key with write scope to call the /consumers/auth endpoint. Generate one in Settings > API Keys.

Events#

Listen for widget events to react to user interactions:

// Listen for an event (returns an unsubscribe function)
const unsubscribe = AVCodexWidget.on("message", (data) => {
  console.log("New message:", data.role, data.content);
});

// Stop listening
unsubscribe();

// Alternative: manually remove a listener
function onOpen() { console.log("Chat opened"); }
AVCodexWidget.on("open", onOpen);
AVCodexWidget.off("open", onOpen);

#### Event Reference

Full API Reference#

Open the Agent from a Custom Button#

Useful on a room-support page where the user expects to tap a "Get Help" button rather than hunt for a floating bubble:

<button onclick="AVCodexWidget.open()">Get help with this room</button>

<script src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"></script>

React Integration#

import { useEffect } from "react";

function App() {
  useEffect(() => {
    // Load the widget script
    const script = document.createElement("script");
    script.src = "https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js";
    script.async = true;
    document.body.appendChild(script);

    return () => {
      // Clean up on unmount
      if (window.AVCodexWidget) {
        window.AVCodexWidget.destroy();
      }
      script.remove();
    };
  }, []);

  return (
    <button onClick={() => window.AVCodexWidget?.open()}>
      Ask the room agent
    </button>
  );
}

Next.js Integration#

"use client";

import Script from "next/script";

export default function ChatWidget() {
  return (
    <Script
      src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"
      strategy="afterInteractive"
      data-greeting="Need help with the conference room?"
    />
  );
}

Auto-Open After a Delay#

Open the chat automatically after 5 seconds. Handy on a new-hire onboarding page for AV programmers:

<script
  src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"
  data-auto-open="5000"
></script>

Track Conversations in Analytics#

AVCodexWidget.on("open", () => {
  // Google Analytics
  gtag("event", "chat_opened", { event_category: "engagement" });
});

AVCodexWidget.on("message", (data) => {
  if (data.role === "user") {
    gtag("event", "chat_message_sent", { event_category: "engagement" });
  }
});

Conditional Widget Loading#

Only load the widget on certain pages. Example: only on the support section of a managed-services portal.

if (window.location.pathname.startsWith("/support")) {
  const script = document.createElement("script");
  script.src = "https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js";
  script.dataset.greeting = "Having trouble with a room? Tell us what's happening.";
  document.body.appendChild(script);
}

Server-Side Auth with React#

import { useEffect } from "react";

function ChatWidget({ user }) {
  useEffect(() => {
    if (!user || !window.AVCodexWidget) return;

    // Call your backend to get a widget token
    fetch("/api/chat-token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email: user.email, name: user.name }),
    })
      .then((res) => res.json())
      .then(({ token }) => {
        window.AVCodexWidget.setUser({
          email: user.email,
          name: user.name,
          token,
        });
      });
  }, [user]);

  return null;
}

The iframe embeds your AVCodex agent directly in the page layout. Use this when you want the chat to be a fixed part of the page (a dedicated "Ask the Room Agent" panel inside a building's conference-room landing page) rather than a floating overlay.

Getting the Iframe Code#

1. Open Share Settings

In your AVCodex agent, click Publish > Share in the navigation.

2. Find the Iframe Card

Look for the Iframe card on the Share page.

3. Copy the Code

Click the code snippet to copy it:

<iframe src="https://your-agent.app.avcodex.com" height="800px" width="100%" frameborder="0" title="Your Agent Name"></iframe>

4. Add to Your Site

Paste the iframe code into your HTML where you want the chat to appear.

Customizing the Iframe#

Adjust dimensions:

<iframe
  src="https://your-agent.app.avcodex.com"
  height="600px"
  width="400px"
  frameborder="0"
  title="Room Support Chat"
></iframe>

Responsive container:

<div style="width: 100%; height: 80vh; min-height: 400px;">
  <iframe
    src="https://your-agent.app.avcodex.com"
    style="width: 100%; height: 100%; border: none;"
  ></iframe>
</div>

WordPress#

For Widget:

1. Go to Appearance > Theme Editor (or use a plugin like "Insert Headers and Footers")
2. Add the widget code before </body> in your theme's footer

For Iframe:

1. Edit your page or post
2. Add a Custom HTML block
3. Paste the iframe code

Webflow#

1. Go to Project Settings > Custom Code
2. For widget: Paste in "Footer Code"
3. For iframe: Add an Embed element to your page

Squarespace#

For Widget:

1. Go to Settings > Advanced > Code Injection
2. Paste in the "Footer" section

For Iframe:

1. Add a Code Block to your page
2. Paste the iframe code

Shopify#

For Widget:

1. Go to Online Store > Themes > Edit code
2. Find theme.liquid and paste before </body>

For Iframe:

1. Edit the page where you want the chat
2. Add a Custom Liquid section
3. Paste the iframe code

Wix#

For Widget:

1. Go to Settings > Custom Code
2. Click Add Code in the Body - End
3. Paste the widget script tag

For Iframe:

1. Add an HTML iframe element to your page
2. Set the source URL to your agent URL

Framer#

For Widget:

1. Go to Site Settings > Custom Code
2. Add the widget script in the "End of <body> tag" section

For Iframe:

1. Add a Code component
2. Paste the iframe embed code

AVCodex automatically handles cross-origin cookie restrictions for iframe and widget embeds. When the agent detects it's running inside an iframe on a different domain, it sets cookies with SameSite=None so the browser allows them in the cross-site context. Both anonymous and authenticated chat work out of the box in iframe embeds, no extra configuration required.

Note: Some browsers (notably Safari with Intelligent Tracking Prevention) may still block third-party cookies in certain configurations. If users have trouble keeping their chat sessions in an iframe embed, consider: 1. Set up a custom domain that's a subdomain of your site (best for iframe embeds, same-site cookies just work). 2. Use server-side auth with `setUser()` to pass a bearer token via PostMessage (bypasses cookies entirely).

How Server-Side Auth Bypasses Cookie Issues#

For agents with authentication enabled, or for maximum compatibility with strict browser privacy settings, the setUser({ token }) approach avoids cookies entirely:

1. Your server calls POST /api/v1/apps/{APP_ID}/consumers/auth with the user's email.
2. The API returns a bearer token.
3. Your frontend passes the token to AVCodexWidget.setUser().
4. The widget sends the token to the iframe via PostMessage.
5. The iframe uses the bearer token for authentication instead of cookies.

This works in cross-origin contexts because PostMessage is not affected by cookie restrictions.

You can configure these settings in:

• Settings page for custom domains
• Access page for authentication settings

If your site uses a strict Content Security Policy, allow the widget script and iframe:

frame-src *.app.avcodex.com;
script-src your-agent.app.avcodex.com;

Replace with your custom domain if you have one configured.

If you're using a nonce-based CSP, add the nonce to the script tag:

<script nonce="YOUR_NONCE" src="https://your-agent.app.avcodex.com/w/chat/avcodex-widget.js"></script>

Widget Not Appearing#

1. Check code placement: Widget code goes before </body>, not inside <head>.
2. Check for conflicts: Other scripts may interfere. Check the browser console for errors.
3. Check agent status: Ensure your agent is published and active.
4. Check CSP: Your site's Content Security Policy may block the script or iframe.
5. Check mobile: If data-hide-on-mobile="true" is set, the widget won't appear on mobile.

Widget Appears But Chat Won't Open#

1. Check the console: Look for network errors or CORS issues.
2. Check the agent URL: Confirm the agent is reachable at the URL in the script src.
3. Check authentication: If auth is enabled, use setUser() with a token or set up a custom domain.

Iframe Shows "Session Not Found"#

This usually means the browser is blocking cookies in a cross-origin iframe context. AVCodex handles this automatically, but strict privacy settings can still get in the way:

1. Safari ITP: Safari aggressively blocks third-party cookies. Use a custom domain (subdomain of your site) or server-side auth with setUser({ token }).
2. Chrome Incognito: Third-party cookies may be blocked by default in Incognito.
3. Browser extensions: Privacy extensions (uBlock Origin, Privacy Badger) may block cross-site cookies.

Iframe Not Loading#

1. Check the URL: The iframe src must match your agent's URL exactly.
2. CSP headers: Your site's Content Security Policy may block iframes.
3. X-Frame-Options: Some hosting providers set X-Frame-Options: DENY by default.

Styling Issues#

1. Z-index conflicts: Use the data-z-index attribute to adjust widget stacking order.
2. Container overflow: For iframe, ensure parent elements don't have overflow: hidden.
3. Mobile display: Use data-hide-on-mobile="true" if the widget conflicts with your mobile layout.
4. Double widget: If you see two widgets, make sure the script tag is only included once. The widget prevents double-initialization, but old v1 and new v2 scripts can coexist.

User Identity Not Working#

1. Check `setUser` timing: Call setUser() after the widget script has loaded. Listen for the ready event if needed:

``javascript AVCodexWidget.on("ready", () => { AVCodexWidget.setUser({ email: "tech@integrator.example" }); }); ``

1. Check token validity: Server-side tokens expire. Generate a fresh token on each page load.
2. Check API key scope: The Builder API key must have write scope to call /consumers/auth.

*AVCodex · Your AV expertise. Amplified by AI.*