Widget Metadata Communication

The widget supports bidirectional communication between the parent page and the embedded chat iframe using the postMessage API. This enables rich integrations where the parent application can send context to the widget and receive events back.

Overview

Direction	Use Case
Parent → Widget	Send user context, session data, custom metadata
Widget → Parent	Receive events like close requests, navigation, ticket creation

Features

Metadata Injection: Parent page can send arbitrary metadata to the widget
Event Notification: Widget notifies parent of user actions and state changes
Mobile State Detection: Automatic detection and handling of mobile/desktop states
Widget Mode Detection: Automatic detection when running in iframe vs standalone mode
Secure Communication: Origin validation for all messages

Window Configuration

When embedding the widget, configure it through the window.AGO object before loading the widget script. These options control authentication, appearance, and behavior.

<script>
    window.AGO = {
        basepath: "https://YOUR-DOMAIN.useago.com/",
        title: "Support Chat",
        prompt: "Hello, how can I help you?",
        colors: { button: "#0069ED" },
        icon: "https://example.com/chat-icon.png",
        jwt: "eyJhbGciOiJFUzI1NiIs...",
        authToken: "external-api-token",
        email: "user@example.com",
        permission: "premium-support",
        notifications: true,
        notificationMessage: "You have {{count}} unread messages",
        hideFooter: true
    };
</script>
<script async src="https://useago.github.io/widgetjs/frame.js"></script>

Option	Type	Description
`basepath`	string	Base URL of your AGO instance (required)
`title`	string	Title displayed in the chat header
`prompt`	string	Welcome message shown to users
`colors`	object	Color customization (e.g. `{ button: "#0069ED" }`)
`panelWidth`	string	Width of the chat panel, e.g. `"700px"` (see Panel size)
`icon`	string	URL to a custom icon for the chat button
`jwt`	string	JWT token for authenticated users (see Widget Authentication)
`authToken`	string	External auth token forwarded to agent tools via `X-Auth-Token` header
`email`	string	User email for identification
`permission`	string	Permission name to override the default permission
`notifications`	boolean	Enable unread message notifications (displays a red badge)
`notificationMessage`	string	Custom notification text (`{{count}}` is replaced with the unread count)
`hideFooter`	boolean	Hide the “Powered by AGO” footer

Panel size

The chat panel is 550px wide by default. Set panelWidth to change it:

<script>
    window.AGO = {
        basepath: "https://YOUR-DOMAIN.useago.com/",
        panelWidth: "700px"
    };
</script>
<script async src="https://useago.github.io/widgetjs/frame.js"></script>


Default	`550px`
Minimum	`400px` — smaller values are raised to it
Maximum	the viewport, less a 40px margin (twice the chat button’s distance from the edge, if you moved it)
Accepted values	a CSS length (`px`, `rem`, `em`, `vw`, `vmin`, `vmax`), a percentage, or a `min()` / `max()` / `clamp()` / `calc()` expression
Ignored when	the viewport is 450px wide or less, where the panel is always fullscreen

Percentages resolve against the viewport, not against any element on your page, because the panel is positioned fixed. panelWidth: "50%" on a 1400px screen is 700px. An invalid value is ignored, the panel stays at 550px, and the reason is logged to the browser console:

[AGO] window.AGO.panelWidth "700" is not a valid CSS length, ignoring. Expected e.g. "700px" or "45rem". Falling back to 550px.

Setting the width from CSS instead

The same value is exposed as a CSS custom property, which lets you vary it with media queries. Set it on #ago-chatbot and it wins over panelWidth — no !important needed:

<style>
    #ago-chatbot { --ago-panel-width: 700px; }

    @media (min-width: 1600px) {
        #ago-chatbot { --ago-panel-width: 900px; }
    }
</style>

Precedence:

Where you set `--ago-panel-width`	Wins over `panelWidth`?
`#ago-chatbot`, with or without `!important`	Yes
`:root` (or `html`), with `!important`	Yes
`:root` (or `html`), without `!important`	No

#ago-chatbot always wins because a value declared on the panel itself takes priority over one it inherits from the page root, which is where panelWidth writes. Setting it on #ago-chatbot is the recommended form: it behaves the same either way, so there is nothing to remember.

Chat content is capped at 768px wide, so a panel wider than that shows empty margins on either side of the conversation.

Updating JWT at Runtime

Use sendJwtToAGO() to update the JWT token after the widget has loaded. This is useful when the user logs in after the widget is already open, or when the JWT token is refreshed.

// Update JWT after user login or token refresh
sendJwtToAGO("eyJhbGciOiJFUzI1NiIs...");

This updates the JWT in both the chat iframe and the notification iframe, so unread counts are fetched with the correct identity.

Updating Auth Token at Runtime

Use sendAuthTokenToAGO() to pass an external authentication token to the widget. This token is forwarded to agent tools (e.g., HTTP request tool) as the X-Auth-Token header, allowing agents to call your authenticated APIs on behalf of the user.

// Pass an external API token to agent tools
sendAuthTokenToAGO("your-external-api-token");

Sending Metadata

Use the sendMetadataToAGO function to pass context from your application to the widget.

// Basic metadata
sendMetadataToAGO({
    userId: 'user-123',
    userEmail: 'user@example.com'
});

// Rich context with custom data
sendMetadataToAGO({
    userId: 'user-123',
    userEmail: 'user@example.com',
    userName: 'John Doe',
    orderId: 'order-456',
    plan: 'premium',
    customData: {
        lastPurchase: '2024-01-15',
        accountAge: 365,
        preferences: {
            language: 'en',
            timezone: 'America/New_York'
        }
    }
});

Metadata Fields Reference

Field	Type	Description
userId	string	Unique user identifier in your system
userEmail	string	User’s email address
userName	string	User’s display name
orderId	string	Current order/transaction ID
plan	string	User’s subscription plan
customData	object	Any additional context (nested objects supported)

Letting the agent use the metadata to answer

By default the metadata is only used for support tickets: it is mapped to labels in Settings → Integrations → Widget & SDK → Metadata Fields Mapping, and appears in the ticket’s private comment and prefilled fields. The AI agent does not see it. Turn on Send metadata to the agent on the same page to also include the metadata in the agent’s prompt. The agent can then answer using it — for example, replying about the right subscription tier without asking the visitor which plan they are on:

sendMetadataToAGO({
    plan: 'premium',
    seatsUsed: 12,
    seatsIncluded: 20,
    renewalDate: '2026-03-01'
});

Good to know:

The whole metadata object is sent with every message, so the agent always sees the latest values — reassign it when your app’s state changes.
The metadata comes from the page embedding the widget, which means a visitor can edit it in their browser. Treat it as information, never as proof: use permissions or a JWT for anything that grants access.
Keep the payload small (under 10 KB). A larger one is dropped rather than sent to the agent.
For data the visitor must not be able to change, use an API Data Source instead: AGO fetches it from your API server-side and adds it to the same conversation.

Usage in React Native WebView

// In React Native, inject JavaScript to set metadata
webViewRef.current.injectJavaScript(`
  sendMetadataToAGO({
    userId: '${userId}',
    userEmail: '${userEmail}',
    sessionData: ${JSON.stringify(sessionData)}
  });
  true; // Required for iOS
`);

Setting Up the Event Listener

The parent page should listen for messages from the widget:

window.addEventListener('message', (event) => {
    // Validate origin for security
    if (event.origin !== 'https://your-ago-domain.com') {
        return;
    }

    // Handle different message types
    switch (event.data.type) {
        case 'CLOSE_CHAT':
            handleCloseChat();
            break;
        case 'THREAD_CREATED':
            handleThreadCreated(event.data.data);
            break;
        case 'TICKET_CREATED':
            handleTicketCreated(event.data.data);
            break;
        case 'NAVIGATE':
            handleNavigation(event.data.data);
            break;
        case 'UNREAD_STAFF_COUNT':
            handleUnreadCount(event.data.count);
            break;
    }
});

Built-in Message Types

CLOSE_CHAT

Sent when the user clicks the close button or requests to minimize the widget.

{
    type: 'CLOSE_CHAT'
}

Use Case: Hide the widget container or minimize to a button.

function handleCloseChat() {
    document.getElementById('widget-container').style.display = 'none';
    document.getElementById('chat-button').style.display = 'block';
}

THREAD_CREATED

Sent when a new conversation thread is started.

{
    type: 'THREAD_CREATED',
    data: {
        threadId: 'thread-uuid',
        agentId: 'agent-uuid',
        agentName: 'Support Agent'
    }
}

Use Case: Track conversation starts in your analytics.

function handleThreadCreated(data) {
    analytics.track('Chat Started', {
        threadId: data.threadId,
        agent: data.agentName
    });
}

TICKET_CREATED

Sent when a support ticket is created from the conversation.

{
    type: 'TICKET_CREATED',
    data: {
        ticketId: 'ticket-123',
        threadId: 'thread-uuid',
        externalId: 'helpscout-ticket-id'
    }
}

Use Case: Show confirmation or update your ticket tracking.

function handleTicketCreated(data) {
    showNotification(`Ticket #${data.ticketId} created`);
    updateTicketList(data.ticketId);
}

NAVIGATE

Sent when the widget requests navigation to a specific page.

{
    type: 'NAVIGATE',
    data: {
        url: '/account/settings',
        target: '_self'
    }
}

Use Case: Handle in-app navigation from agent responses.

function handleNavigation(data) {
    if (data.target === '_blank') {
        window.open(data.url, '_blank');
    } else {
        router.push(data.url);
    }
}

UNREAD_STAFF_COUNT

Sent periodically (every 30 seconds) by the notification frame to inform the parent page of unread staff messages. The notification frame is a hidden iframe that polls for unread messages. It only reports counts for users who have an existing widget session (i.e., a widget ID in localStorage from a previous chat interaction) — new visitors with no prior conversations will not trigger any polls. Enabling notifications: Set notifications: true in the window.AGO configuration object:

<script>
    window.AGO = {
        basepath: "https://YOUR-DOMAIN.useago.com/",
        notifications: true
    };
</script>
<script async src="https://useago.github.io/widgetjs/frame.js"></script>

When enabled, the standard widget automatically displays a red badge on the chat button. If you build a custom integration, listen for the event yourself:

{
    type: 'UNREAD_STAFF_COUNT',
    count: 3
}

Use Case: Display an unread message badge on your chat button.

function handleUnreadCount(count) {
    const badge = document.getElementById('chat-badge');
    if (count > 0) {
        badge.textContent = count;
        badge.style.display = 'block';
    } else {
        badge.style.display = 'none';
    }
}

JWT authentication: If your widget uses JWT authentication, call sendJwtToAGO(token) whenever the token is refreshed. This updates both the chat iframe and the notification frame so that unread counts are fetched with the correct identity.

Complete Integration Examples

Basic Web Integration

<!DOCTYPE html>
<html>
<head>
    <title>My App with AGO Widget</title>
</head>
<body>
<h1>My Application</h1>

<div id="chat-button" onclick="openWidget()">Chat with us</div>
<div id="widget-container" style="display: none;">
    <!-- Widget will be injected here -->
</div>

<script src="https://useago.github.io/widgetjs/frame.js"></script>
<script>
    // Configure widget
    window.AGO = {
        basepath: 'https://your-ago-domain.com/',
        email: 'user@example.com'
    };

    // Set up event listener
    window.addEventListener('message', (event) => {
        if (event.data.type === 'CLOSE_CHAT') {
            closeWidget();
        }
        if (event.data.type === 'TICKET_CREATED') {
            console.log('Ticket created:', event.data.data.ticketId);
        }
    });

    function openWidget() {
        document.getElementById('widget-container').style.display = 'block';
        document.getElementById('chat-button').style.display = 'none';

        // Send current context
        sendMetadataToAGO({
            userId: getCurrentUserId(),
            currentPage: window.location.pathname,
            cartItems: getCartItems()
        });
    }

    function closeWidget() {
        document.getElementById('widget-container').style.display = 'none';
        document.getElementById('chat-button').style.display = 'block';
    }
</script>
</body>
</html>

React Integration

import { useEffect, useCallback } from 'react';

function ChatWidget({ user, isOpen, onClose }) {
    const handleMessage = useCallback((event) => {
        // Validate origin
        if (event.origin !== process.env.REACT_APP_AGO_DOMAIN) return;

        switch (event.data.type) {
            case 'CLOSE_CHAT':
                onClose();
                break;
            case 'TICKET_CREATED':
                toast.success(`Ticket ${event.data.data.ticketId} created`);
                break;
            case 'NAVIGATE':
                navigate(event.data.data.url);
                break;
        }
    }, [onClose]);

    useEffect(() => {
        window.addEventListener('message', handleMessage);
        return () => window.removeEventListener('message', handleMessage);
    }, [handleMessage]);

    useEffect(() => {
        if (isOpen && user) {
            window.sendMetadataToAGO({
                userId: user.id,
                userEmail: user.email,
                userName: user.name,
                plan: user.subscription?.plan
            });
        }
    }, [isOpen, user]);

    if (!isOpen) return null;

    return (
        <div className="widget-container">
            <iframe
                id="ago-widget-iframe"
                src={`${process.env.REACT_APP_AGO_DOMAIN}/widget`}
                title="Chat Widget"
            />
        </div>
    );
}

Ticket Integration

When tickets are created from conversations, metadata is automatically included and formatted for support agents.

HelpScout Integration

Metadata appears as formatted JSON in private comments:

You can find the full conversation here: https://app.com/chat/thread-123

Metadata:
{
  "userId": "user-123",
  "orderId": "order-456",
  "sessionId": "session-789",
  "customData": {
    "plan": "premium",
    "region": "us-east"
  }
}

Zendesk Integration

Metadata is added to custom ticket fields and internal notes, providing support agents with comprehensive context.

Security Considerations

Origin Validation

Always validate the message origin:

window.addEventListener('message', (event) => {
    const allowedOrigins = [
        'https://your-ago-domain.com',
        'https://widget.useago.com'
    ];

    if (!allowedOrigins.includes(event.origin)) {
        console.warn('Message from unauthorized origin:', event.origin);
        return;
    }

    // Process message...
});

Sensitive Data

Do not send: Passwords, API keys, tokens, credit card numbers
Safe to send: User IDs, order IDs, plan names, page context, preferences

Content Security Policy

If using CSP, ensure your policy allows communication with the widget:

<meta http-equiv="Content-Security-Policy"
      content="frame-src https://your-ago-domain.com;
               script-src 'self' https://useago.github.io;">

Troubleshooting

Widget Not Receiving Metadata

Messages Not Being Received

Check origin validation in your event listener
Ensure widget domain is correct
Check browser console for blocked cross-origin messages

Metadata Not Appearing in Tickets

Verify metadata was sent before ticket creation
Check that metadata format is valid JSON
Ensure ticketing integration is properly configured

Browser Compatibility

The postMessage API is supported in all modern browsers:

Browser	Minimum Version
Chrome	1+
Firefox	3+
Safari	4+
Edge	12+
iOS Safari	3.2+
Android Chrome	18+

No polyfills required.

Widget Authentication - Configure widget security
Widget Configuration - Widget appearance and behavior
Ticketing Tool - Ticket creation from conversations
Mobile Authentication - Mobile SDK authentication

Integrate

Overview

Features

Parent to Widget Communication

Window Configuration

Panel size

Setting the width from CSS instead

Updating JWT at Runtime

Updating Auth Token at Runtime

Sending Metadata

Metadata Fields Reference

Letting the agent use the metadata to answer

Usage in React Native WebView

Widget to Parent Communication

Setting Up the Event Listener

Built-in Message Types

CLOSE_CHAT

THREAD_CREATED

TICKET_CREATED

NAVIGATE

UNREAD_STAFF_COUNT

Complete Integration Examples

Basic Web Integration

React Integration

Ticket Integration

HelpScout Integration

Zendesk Integration

Security Considerations

Origin Validation

Sensitive Data

Content Security Policy

Troubleshooting

Browser Compatibility

​Overview

​Features

​Parent to Widget Communication

​Window Configuration

​Panel size

​Setting the width from CSS instead

​Updating JWT at Runtime

​Updating Auth Token at Runtime

​Sending Metadata

​Metadata Fields Reference

​Letting the agent use the metadata to answer

​Usage in React Native WebView

​Widget to Parent Communication

​Setting Up the Event Listener

​Built-in Message Types

​CLOSE_CHAT

​THREAD_CREATED

​TICKET_CREATED

​NAVIGATE

​UNREAD_STAFF_COUNT

​Complete Integration Examples

​Basic Web Integration

​React Integration

​Ticket Integration

​HelpScout Integration

​Zendesk Integration

​Security Considerations

​Origin Validation

​Sensitive Data

​Content Security Policy

​Troubleshooting

​Browser Compatibility

​Related Documentation

Overview

Features

Parent to Widget Communication

Window Configuration

Panel size

Setting the width from CSS instead

Updating JWT at Runtime

Updating Auth Token at Runtime

Sending Metadata

Metadata Fields Reference

Letting the agent use the metadata to answer

Usage in React Native WebView

Widget to Parent Communication

Setting Up the Event Listener

Built-in Message Types

CLOSE_CHAT

THREAD_CREATED

TICKET_CREATED

NAVIGATE

UNREAD_STAFF_COUNT

Complete Integration Examples

Basic Web Integration

React Integration

Ticket Integration

HelpScout Integration

Zendesk Integration

Security Considerations

Origin Validation

Sensitive Data

Content Security Policy

Troubleshooting

Browser Compatibility

Related Documentation