Custom Data

Pass user data and custom metadata to the Alhena chat widget for personalized AI interactions and custom tool integrations.

Alhena's Chat SDK lets you pass user metadata to personalize AI conversations and integrate with your backend systems. This page explains how to configure public metadata for AI prompts and private tokens for secure API calls.

Overview

User metadata serves two purposes:

1. Personalization - Public metadata is available to the AI for context-aware responses

2. Backend Integration - Private metadata (API tokens, user IDs) enables custom tools to call your APIs

---

Quick Reference

Configuration	Where	When to Use
document.gleenConfig.userMetadata	Initial config	Set data at widget load
window.gleenWidget.setUserMetadata()	Runtime	Update data dynamically

Key Prefix	Visibility	Example
No prefix	Public (AI can see)	email, name, plan
_ underscore	Private (hidden from AI)	_bearer_token, _user_id

---

Public vs. Private Metadata

Public Metadata

Keys without an underscore prefix are public. The AI can use this data to personalize responses.

document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    userMetadata: {
        email: '[e-mail]',    // AI sees this
        name: 'John Doe',              // AI sees this
        plan: 'premium',               // AI sees this
        locale: 'en-US'                // AI sees this
    }
};

How the AI uses public metadata:

• Greet users by name: "Hi John, how can I help?"

• Reference account type: "As a premium member, you have access to..."

• Personalize recommendations based on preferences

Private Metadata

Keys starting with _ (underscore) are private. These are never exposed to the AI but are available to custom API tools configured in your dashboard.

document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    userMetadata: {
        _bearer_token: 'eyJhbGciOiJIUzI1NiIs...',  // Hidden from AI
        _user_id: '12345',                          // Hidden from AI
        _session_id: 'abc-123-xyz'                  // Hidden from AI
    }
};

Use private metadata for:

• API authentication tokens

• Internal user/session identifiers

• Sensitive data that shouldn't appear in AI context

---

Setting Metadata

At Initialization

Pass metadata when the widget loads:

<script>
document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    userMetadata: {
        // Public - available to AI
        email: '[e-mail]',
        name: 'Jane Smith',
        membership: 'gold',

        // Private - only for API tools
        _api_token: 'secret-token-value',
        _customer_id: 'cust_12345'
    }
};
</script>
<script src="https://app.alhena.ai/sdk/gleenWidget.js"></script>

Dynamic Updates

Update metadata at runtime using setUserMetadata(key, value). Each call sets a single field:

// After user logs in
window.gleenWidget.setUserMetadata('email', currentUser.email);
window.gleenWidget.setUserMetadata('name', currentUser.name);
window.gleenWidget.setUserMetadata('_session_token', currentUser.sessionToken);

// Update a specific field
window.gleenWidget.setUserMetadata('plan', 'enterprise');

---

Common Use Cases

User Identification

Pass user details after authentication for personalized support:

// When user logs in
function onUserLogin(user) {
    window.gleenWidget.setUserMetadata('email', user.email);
    window.gleenWidget.setUserMetadata('name', user.displayName);
    window.gleenWidget.setUserMetadata('account_type', user.accountType);
    window.gleenWidget.setUserMetadata('signup_date', user.createdAt);
    window.gleenWidget.setUserMetadata('_user_id', user.id);
}

Passing Cart Data

Pass the customer's current cart to enable the AI to answer questions about items in their cart, provide checkout assistance, or make recommendations.

Shopify stores: Cart data is passed automatically when you install the Alhena widget. No additional configuration needed.

For other platforms, fetch cart data and pass it using setUserMetadata:

WooCommerce:

window.gleenWidget.on('widget:loaded', async function() {
    try {
        // WooCommerce Store API (requires WC 5.0+)
        const response = await fetch('/wp-json/wc/store/v1/cart');
        const cart = await response.json();

        const cartData = {
            items: cart.items.map(item => ({
                title: item.name,
                quantity: item.quantity,
                price: item.prices.price / 100,
                options: item.variation || []
            })),
            currency: cart.totals.currency_code,
            subtotal: parseInt(cart.totals.total_items) / 100,
            checkout_url: window.location.origin + '/checkout/'
        };

        window.gleenWidget.setUserMetadata('current_cart', cartData);
    } catch (error) {
        console.error('Failed to fetch cart:', error);
    }
});

Magento:

window.gleenWidget.on('widget:loaded', async function() {
    try {
        const response = await fetch('/rest/V1/carts/mine', {
            headers: {
                'Authorization': 'Bearer ' + customerToken
            }
        });
        const cart = await response.json();

        const cartData = {
            items: cart.items.map(item => ({
                title: item.name,
                quantity: item.qty,
                price: item.price,
                options: item.product_option?.extension_attributes || []
            })),
            currency: cart.currency.quote_currency_code,
            subtotal: cart.subtotal,
            checkout_url: window.location.origin + '/checkout/'
        };

        window.gleenWidget.setUserMetadata('current_cart', cartData);
    } catch (error) {
        console.error('Failed to fetch cart:', error);
    }
});

Custom Platform / Generic:

window.gleenWidget.on('widget:loaded', function() {
    // Replace with your cart data source
    const cart = getYourCartData();

    const cartData = {
        items: cart.items.map(item => ({
            title: item.productName,
            quantity: item.quantity,
            price: item.unitPrice,
            options: item.selectedOptions || []
        })),
        currency: cart.currency || 'USD',
        subtotal: cart.subtotalAmount,
        checkout_url: window.location.origin + '/checkout'
    };

    window.gleenWidget.setUserMetadata('current_cart', cartData);
});

// Update cart when it changes
function onCartUpdated(cart) {
    const cartData = {
        items: cart.items.map(item => ({
            title: item.productName,
            quantity: item.quantity,
            price: item.unitPrice,
            options: item.selectedOptions || []
        })),
        currency: cart.currency || 'USD',
        subtotal: cart.subtotalAmount,
        checkout_url: window.location.origin + '/checkout'
    };

    window.gleenWidget.setUserMetadata('current_cart', cartData);
}

Cart data structure:

Field	Type	Description
items	Array	List of cart items
items[].title	String	Product name
items[].quantity	Number	Quantity in cart
items[].price	Number	Unit price
items[].options	Array	Selected variants/options
currency	String	Currency code (USD, EUR, etc.)
subtotal	Number	Cart subtotal amount
checkout_url	String	URL to checkout page

Backend API Integration

Pass tokens for custom tools that call your APIs:

// Get token from your authentication system
const userToken = await getAuthToken();

document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    userMetadata: {
        email: currentUser.email,
        _bearer_token: userToken,
        _api_key: process.env.API_KEY
    }
};

Setting up API Tools: Create custom API tools in the Alhena dashboard under Settings > API Tools. These tools can use private metadata values to authenticate requests to your backend.

---

Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Personalized Chat Widget</title>
</head>
<body>

<div id="user-info">
    <span id="greeting">Welcome, Guest</span>
    <button id="login-btn">Log In</button>
    <button id="logout-btn" style="display:none">Log Out</button>
</div>

<!-- Alhena SDK with initial metadata -->
<script>
// Initial configuration for anonymous users
document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    userMetadata: {
        visitor_type: 'anonymous',
        page_url: window.location.href
    }
};
</script>
<script src="https://app.alhena.ai/sdk/gleenWidget.js"></script>

<script>
// Simulated user data
const mockUser = {
    id: 'user_12345',
    email: '[e-mail]',
    name: 'Jane Smith',
    plan: 'premium',
    token: 'eyJhbGciOiJIUzI1NiIs...'
};

// Login handler
document.getElementById('login-btn').addEventListener('click', function() {
    // Update UI
    document.getElementById('greeting').textContent = 'Welcome, ' + mockUser.name;
    document.getElementById('login-btn').style.display = 'none';
    document.getElementById('logout-btn').style.display = 'inline';

    // Update chat widget with user data
    // Public data for AI personalization
    window.gleenWidget.setUserMetadata('email', mockUser.email);
    window.gleenWidget.setUserMetadata('name', mockUser.name);
    window.gleenWidget.setUserMetadata('plan', mockUser.plan);
    window.gleenWidget.setUserMetadata('visitor_type', 'authenticated');

    // Private data for API integrations
    window.gleenWidget.setUserMetadata('_user_id', mockUser.id);
    window.gleenWidget.setUserMetadata('_bearer_token', mockUser.token);
});

// Logout handler
document.getElementById('logout-btn').addEventListener('click', function() {
    // Update UI
    document.getElementById('greeting').textContent = 'Welcome, Guest';
    document.getElementById('login-btn').style.display = 'inline';
    document.getElementById('logout-btn').style.display = 'none';

    // Reset to anonymous state
    window.gleenWidget.setUserMetadata('visitor_type', 'anonymous');
    window.gleenWidget.setUserMetadata('email', null);
    window.gleenWidget.setUserMetadata('name', null);
    window.gleenWidget.setUserMetadata('plan', null);
    window.gleenWidget.setUserMetadata('_user_id', null);
    window.gleenWidget.setUserMetadata('_bearer_token', null);
});
</script>

</body>
</html>

---

Security Best Practices

1. Never expose sensitive credentials - Always use the _ prefix for tokens and secrets

2. Rotate tokens - Use short-lived tokens when possible

3. Validate on backend - Your API tools should still validate tokens server-side

4. Limit metadata scope - Only pass data that's needed for personalization or integration

---

Related Resources

• JavaScript API - Complete method reference

• Events - Widget event reference

• Examples - Code examples for common use cases