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

E-commerce Personalization

Provide shopping context for better product recommendations:

document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    userMetadata: {
        customer_segment: 'returning',
        preferred_category: 'electronics',
        currency: 'USD',
        _customer_id: 'cust_abc123'
    }
};

Multi-language Support

Combine with locale settings for proper language handling:

document.gleenConfig = {
    company: 'your-company-key',
    apiBaseUrl: 'https://app.alhena.ai',
    locale: 'es',  // UI strings in Spanish
    userMetadata: {
        preferred_language: 'Spanish',
        region: 'LATAM'
    }
};

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.

---

Data Persistence

• Metadata is stored in the browser session

• Data persists across page navigations within the same session

• Clearing browser storage resets metadata

• Call setUserMetadata() after page loads if you need to restore data

// Restore metadata from your app's state
window.gleenWidget.on('widget:loaded', function() {
    if (isLoggedIn()) {
        window.gleenWidget.setUserMetadata('email', getUserEmail());
        window.gleenWidget.setUserMetadata('name', getUserName());
        window.gleenWidget.setUserMetadata('_token', getSessionToken());
    }
});

---

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