Widget Metadata Communication

Bidirectional communication between parent page and chat widget

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

---

Parent to Widget Communication

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: "[e-mail]",
        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" })
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

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: '[e-mail]'
});

// Rich context with custom data
sendMetadataToAGO({
    userId: 'user-123',
    userEmail: '[e-mail]',
    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)

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
`);

---

Widget to Parent Communication

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: '[e-mail]'
    };

    // 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

1. Ensure the widget script has finished loading before calling sendMetadataToAGO
2. Check browser console for errors
3. Verify sendMetadataToAGO is available globally (it is defined by frame.js)

Messages Not Being Received

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

Metadata Not Appearing in Tickets

1. Verify metadata was sent before ticket creation
2. Check that metadata format is valid JSON
3. 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.

---

Related Documentation

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