🤖 Luka Embed Widget Documentation

Embedding instructions for: https://chat-burning-meme-app.dexguru.biz

🎨 Widget Title

Customize your widget settings. The code below will update automatically.

Display Mode

Widget Language

Color Theme

Position

AI Agent

Widget Title

Welcome Message

📋 Your Embed Code

Copy this code and paste it into your HTML, just before the closing </body> tag.

<script
    src="https://chat-burning-meme-app.dexguru.biz/luka_embed.js"
    data-luka-id="default"
    data-mode="bubble"
    data-position="bottom-right"
    data-theme="auto"
    data-sub-agent="crypto_analyst"
    data-api-url="https://chat-burning-meme-app.dexguru.biz"
></script>

💡 Quick Start

The code automatically updates as you change settings above. Just copy and paste!

🎮 Widget Controls

Use these buttons to interact with the widget programmatically:

🎨 Select Theme

Light

Dark

Ocean

Sunset

Auto (System)

🤖 Select Sub-Agent:

📐 Panel Width:

400px

📝 Widget Title:

💬 Greeting Message (optional):

📚 Advanced Configuration Reference

Detailed documentation for advanced features and configuration options.

All Available Options

Attribute	Values	Default	Description
data-mode	bubble, copilot, inline	bubble	Display mode
data-locale	en, ru, auto	auto (browser)	UI and LLM language
data-theme	auto, light, dark, ocean, sunset	auto	Color theme
data-position	bottom-right, bottom-left	bottom-right	Widget position (bubble mode)
data-sub-agent	crypto_analyst, etc.	(default)	AI agent persona
data-title	any string	Luka Assistant	Widget header title
data-greeting	any string	(none)	Initial greeting message
data-api-url	URL	(auto)	Backend API URL

🤖 Sub-Agent Configuration

Sub-agents allow you to customize the AI assistant's persona, welcome screen suggestions, and behavior for different use cases.

How Sub-Agents Work

When you specify a <code>data-sub-agent</code> attribute, the embed widget:

Loads the sub-agent configuration from the backend
Displays customized welcome screen suggestions based on the agent's persona
Passes the sub-agent ID to CopilotKit, which forwards it to the backend
Uses agent-specific behavior and context throughout the conversation

Available Sub-Agents

Sub-agents are configured on the backend. Common examples include:

<code>crypto_analyst</code> - Specialized in cryptocurrency and blockchain analysis
<code>defi_alert_bot</code> - DeFi alerts and monitoring assistant
<code>prompt_engineer</code> - Prompt engineering and optimization specialist
<code>general_luka</code> - Default general-purpose assistant (Luka)

To see all available sub-agents, check the backend API endpoint: <code>https://chat-burning-meme-app.dexguru.biz/api/copilotkit/sub-agents</code>

Usage Example

// Embed with crypto analyst sub-agent<script src="https://chat-burning-meme-app.dexguru.biz/luka_embed.js"data-sub-agent="crypto_analyst"data-api-url="https://chat-burning-meme-app.dexguru.biz" ></script>

💡 Note:

If no <code>data-sub-agent</code> is specified, the widget uses the default sub-agent configured on the backend (typically <code>general_luka</code>).

The sub-agent affects the welcome screen suggestions and initial conversation context, similar to using <code>?subAgent=crypto_analyst</code> in the main chat interface.

🔐 Authentication & User Context

This section explains how authentication will work with the embed widget and how user context flows through to the backend.

Authentication Flow

The embed widget supports passing authentication tokens that will be forwarded to the <code>ag_ui_gateway</code> backend for user identification and authorization.

// Configure widget with auth token (before script loads)
window.LukaWidgetConfig = {
  authToken: "your-jwt-token-here"
};

// Widget sends token in Authorization header
// Authorization: Bearer your-jwt-token-here

// Authorization: Bearer your-jwt-token-here
// ag_ui_gateway middleware extracts and validates token
// User context injected into request.state

Token Format

The widget expects a JWT token that will be sent in the <code>Authorization</code> header with the <code>Bearer</code> prefix:

// Token structure (JWT){user_id: 123,platform: "web",token_type: "authenticated" | "guest",permissions: ["read:threads", "write:messages"],exp: 1234567890}

Backend Processing (ag_ui_gateway)

The <code>ag_ui_gateway</code> processes authentication in the following order:

Token Extraction: Middleware extracts token from <code>Authorization: Bearer <token></code> header
Token Validation: Token is validated using <code>TokenManager.validate_token()</code>
User Context Injection: Validated user data is injected into <code>request.state</code>:
Request Processing: API endpoints use <code>request.state.user_id</code> for thread management and user-specific operations
- request.state.user_id - Numeric user ID
- request.state.platform - Platform identifier (e.g., "web", "telegram")
- request.state.token_type - "authenticated" or "guest"
- request.state.is_guest - Boolean flag
- request.state.permissions - Array of permission strings
- request.state.authenticated - Boolean authentication status

💡 Implementation Status:

Authentication token passing is planned for future implementation. Currently, the widget operates in guest mode. When implemented, tokens will be:

Stored securely in the widget configuration
Sent in the <code>Authorization</code> header for all API requests
Validated by <code>ag_ui_gateway</code> middleware
Used to associate conversations with authenticated users

📄 Page Context

Page context allows you to provide the LLM with information about the current page for more context-aware conversations.

Context Object Structure

{url: string,           // url: string - Current page URLtitle: string,         // title: string - Page titledescription: string,  // description: string - Meta descriptiontopic: string,        // topic: string - Primary content topicstage: string,         // stage: string - User journey stageproduct: {                    // product: object - Product/service infoid: string,name: string,category: string,price: number},userSegment: string,   // userSegment: string - User persona/segmentcustom: {                    // custom: object - Custom domain-specific data[key: string]: any}}

Usage Examples

E-commerce Product Page

window.LukaWidgetConfig = {pageContext: {url: window.location.href,title: document.title,topic: "Product Information",product: {id: "PROD-12345",name: "Wireless Headphones",category: "Electronics",price: 199.99},stage: "browsing"}};

Support Page

window.LukaWidgetConfig = {pageContext: {url: "/support/faq",topic: "Frequently Asked Questions",stage: "support",userSegment: "premium"}};

Checkout Page

window.LukaWidgetConfig = {pageContext: {url: "/checkout",topic: "Order Completion",stage: "checkout",custom: {cartValue: 299.97,items: 3,shippingMethod: "express"}}};

💡 Implementation Status:

Page context passing is planned for future implementation. When implemented, the context will be:

Passed to the LLM at conversation start
Used to provide context-aware responses
Updated dynamically as users navigate between pages
Included in conversation history for better continuity

🔍 Widget Status

Checking widget status...

💡 Note:

This documentation page is available at <code>https://chat-burning-meme-app.dexguru.biz/embed</code> on every deployment.

The widget supports three modes:

Bubble mode: Floating button with popup panel (default)

Copilot mode: Right sidebar with collapse handle

Inline mode: Toggleable floating panel with no header, full chat interface

If the widget doesn't appear, check the browser console for any errors. Make sure CORS is properly configured on the backend.