AI Chat Widget

The TM AI Chat Widget feature provides a powerful way to create interactive visual components that can be dynamically rendered within AI Chat conversations. These widgets allow AI agents to present data, visualizations, and interactive content to users in a structured and visually appealing format.

Purpose: TM AI Chat Widget enables developers to create reusable UI components that AI agents can invoke during conversations. These widgets transform raw data into rich visual presentations, such as charts, document previews, data tables, or custom HTML interfaces. This bridges the gap between conversational AI and visual data representation.

Function: The DocType allows you to define HTML templates (with Jinja2 support), CSS styling, and JSON schemas that specify what data the widget expects. When an AI agent determines a widget should be displayed, it generates the required data according to the schema, and the widget is rendered in real-time within the chat interface. Widgets are isolated using Shadow DOM to prevent style conflicts and support advanced features like Frappe Charts integration.

Role Required

System Manager - Full access to create, read, update, delete, and manage TM AI Chat Widget documents

Field	Description
Name	Unique identifier for the widget (e.g., "chart", "document_preview"). This name is used by AI agents to reference and invoke the widget.
Description	A clear description of what the widget does and when it should be used. This description is provided to AI agents to help them determine when to use this widget. Should be detailed and specific.
Application	Links the widget to a specific My Application. This field is mandatory for custom widgets and cannot be changed after creation. System-generated widgets don't require this.
System Generated	Checkbox indicating whether this widget is part of the core system (checked) or a custom widget created by users (unchecked). System widgets cannot be modified.
Input Schema (JSON)	JSON Schema definition that specifies the structure and data types the widget expects. Must be valid JSON. This schema tells AI agents what data to provide when calling the widget. Includes properties, types, required fields, and validation rules.
Preview Sample Data (JSON)	Optional JSON payload used for testing and previewing the widget in the form. Should match the Input Schema structure. Helps developers test the widget rendering without needing to trigger it from an AI conversation.
Template HTML	HTML template with Jinja2 syntax support. Defines the visual structure of the widget. Can access all data passed via the Input Schema. Supports loops, conditionals, filters, and other Jinja2 features. Required field.
CSS	Custom CSS styling for the widget. Applied within a Shadow DOM boundary to prevent conflicts with the main application styles. Can use CSS variables for theme compatibility. Optional field.

Procedure

Access the widget list from the TechMaju AI module in your workspace or directly navigate to /app/tm-ai-chat-widget.

This opens the widget creation form.

Step 2.2: Fill in General Information

Name: Enter a unique, descriptive name for your widget (e.g., "saleschart", "customercard", "task_list")
Description: Write a detailed description explaining:
- What the widget displays
- When it should be used
- What data it visualizes
- Example: "Generates interactive data visualizations (Line, Bar, Pie, Percentage, Heatmap) to display trends, comparisons, or distributions. Use this widget when the user requests a 'chart', 'graph', 'visual', or wants to analyze numeric data trends over time or categories."
Application: Select the My Application this widget belongs to (for custom widgets)
System Generated: Leave unchecked (only system widgets should have this checked)

Step 3.1: Define Input Schema (JSON)

Create a JSON Schema that defines what data your widget needs:

{
  "type": "object",
  "required": ["title", "data"],
  "properties": {
    "title": {
      "type": "string",
      "description": "Title to display above the chart"
    },
    "data": {
      "type": "object",
      "description": "Chart data configuration",
      "properties": {
        "labels": {
          "type": "array",
          "items": {"type": "string"},
          "description": "X-axis labels"
        },
        "datasets": {
          "type": "array",
          "description": "Data series to plot"
        }
      }
    },
    "chartType": {
      "type": "string",
      "enum": ["line", "bar", "pie", "percentage"],
      "default": "line",
      "description": "Type of chart to render"
    }
  }
}

Best Practices for Schema: - Use descriptive property names - Include detailed descriptions for each field - Specify required vs. optional fields - Use enums for limited value sets - Add default values where appropriate - Keep the schema as simple as possible while meeting requirements

Step 3.2: Create Preview Sample Data (Optional)

Provide sample data matching your schema for testing:

{
  "title": "Monthly Sales Performance",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
    "datasets": [
      {
        "name": "Revenue",
        "values": [12000, 15000, 18000, 16000, 21000]
      }
    ]
  },
  "chartType": "line"
}

Step 4.1: Write Template HTML

Create your HTML template using Jinja2 syntax. You have access to all properties defined in your Input Schema:

<div class="widget-container">
    <h3 class="widget-title">{{ title }}</h3>

    {% if chartType == "line" %}
    <div class="chart-wrapper" data-chart-type="line">
        <div id="chart" data-labels='{{ data.labels | tojson }}' 
             data-datasets='{{ data.datasets | tojson }}'></div>
    </div>
    {% endif %}

    {% if data.datasets %}
    <div class="data-summary">
        <p>Total datasets: {{ data.datasets | length }}</p>
    </div>
    {% endif %}
</div>

Template Features: - Full Jinja2 support (loops, conditionals, filters) - Access to all schema properties - Can use Jinja2 filters like tojson, default, length - Support for complex data structures

For Chart Widgets: - Use data-chart-type attribute to specify chart type - Mark charts with isChart: true in the data - Charts are automatically initialized using Frappe Charts library

Step 4.2: Add Custom CSS Styling

Define styles for your widget. Remember these styles are scoped to the Shadow DOM:

.widget-container {
    padding: 1.5rem;
    background: var(--card-bg);
    border-radius: 8px;
    border: 1px solid var(--border-color);
}

.widget-title {
    font-size: 1.25rem;
    font-weight: 600;
    margin-bottom: 1rem;
    color: var(--text-color);
}

.chart-wrapper {
    min-height: 300px;
    margin: 1rem 0;
}

.data-summary {
    margin-top: 1rem;
    padding-top: 1rem;
    border-top: 1px solid var(--border-color);
    font-size: 0.875rem;
    color: var(--text-muted);
}

CSS Best Practices: - Use CSS custom properties (variables) for theme compatibility - Common variables: --card-bg, --border-color, --text-color, --text-muted, --primary-color - Avoid absolute positioning that might break in different contexts - Test in both light and dark themes - Keep specificity low to allow easy overrides

Click the Save button to persist your widget configuration.

Step 5.2: Use the Preview Feature

Click the Preview button in the toolbar
This opens a dialog showing your widget rendered with the Preview Sample Data
The preview uses the same rendering engine as the live chat interface
Check for:
- Correct data rendering
- Proper styling
- No JavaScript errors in console
- Responsive layout
- Chart initialization (if applicable)

Step 5.3: Iterate and Refine

Make adjustments to template, CSS, or schema as needed
Save and preview again
Repeat until satisfied with the output

6. Integrating with AI Chat Agents

Navigate to the TM AI Chat Agent you want to enable this widget for
In the Widgets child table, add a new row
Select your newly created widget from the dropdown
Save the agent

Step 6.2: How AI Agents Use Widgets

When a user's message indicates that visual output would be helpful, the AI agent: 1. Determines which widget is most appropriate based on widget descriptions 2. Generates data matching the widget's Input Schema 3. Calls the widget as a "tool" with the generated data 4. The system renders the widget template with the provided data 5. The rendered widget appears in the chat interface

Example Flow:

User: "Show me a chart of sales for the last 5 months"
  ↓
Agent analyzes request and determines "chart" widget is appropriate
  ↓
Agent generates data according to chart widget's schema
  ↓
System renders chart widget with data
  ↓
User sees interactive chart in chat interface

7. Advanced Features

Step 7.1: Multiple Widgets Per Message

An AI agent can render multiple widgets in a single response. Each widget appears as a separate block in the conversation.

The system automatically validates that data provided by the AI agent matches the Input Schema. Invalid data will result in a rendering error.

Step 7.3: Chart-Specific Features

For chart widgets: - Set isChart: true in the data object - Use data-chart-type attribute on the chart container - Supported chart types: line, bar, pie, percentage, heatmap - Charts are interactive with hover tooltips - Automatically styled to match theme

Best Practices

Single Responsibility: Each widget should do one thing well. Create separate widgets for different visualization types rather than one complex multi-purpose widget.
Clear Descriptions: Write widget descriptions that clearly explain:
- What data the widget displays
- When to use it vs. other similar widgets
- Keywords that should trigger its use
- Example use cases
Schema Simplicity: Keep Input Schemas as simple as possible. Complex nested structures increase the chance of AI agents generating invalid data.
Error Handling in Templates: Use Jinja2 conditional checks to handle missing or invalid data gracefully:
```
{% if data %}
    
{% else %}
    <p>No data available</p>
{% endif %}
```
Responsive Design: Ensure widgets work on different screen sizes. Use relative units (%, rem) instead of fixed pixels where possible.

Performance Optimization

Template Efficiency: Avoid complex computations in templates. Pre-process data in the AI agent when possible.
CSS Efficiency: Use efficient selectors and avoid deep nesting. Shadow DOM already provides isolation.
Data Size: Keep data payloads reasonable. Very large datasets should be paginated or summarized.
Chart Performance: For charts with many data points, consider aggregating or sampling data before visualization.

Security Considerations

Data Sanitization: Never use | safe filter on user-provided data in templates unless absolutely necessary and data is sanitized.
Access Control: Widgets inherit the permission context of the AI Chat Agent. Sensitive data should only be included in widgets attached to restricted agents.
Testing: Always test widgets with various data inputs to ensure they handle edge cases properly.

Maintenance and Versioning

Documentation: Document any special requirements or behaviors in the widget description.
Backward Compatibility: When updating existing widgets, ensure changes don't break AI agents that already use them.
Testing After Updates: After modifying a widget, test it with all AI agents that use it.
Naming Conventions: Use clear, consistent naming for widgets (e.g., verbnoun pattern: "showchart", "display_table").

Integration Best Practices

Progressive Enhancement: Design widgets to work even if some optional data fields are missing.
User Feedback: Include loading states and error messages in your templates when appropriate.
Accessibility: Use semantic HTML and include appropriate ARIA labels for screen readers.
Theme Compatibility: Always use CSS variables for colors to ensure widgets work in both light and dark themes.

Common Use Cases

1. Data Visualization Widgets

Charts and graphs (line, bar, pie)
Heatmaps and distribution plots
Timeline visualizations
Comparison tables

2. Document Display Widgets

Document preview cards
Field-value tables
Status indicators with metadata
Formatted text with styling

3. Interactive Widgets

Forms embedded in chat
Button groups for quick actions
Selection controls
Interactive filters

4. Information Cards

User profiles
Product cards
Notification displays
Summary boxes

Troubleshooting

Symptoms: Widget appears as an error message or doesn't render at all

Possible Causes & Solutions: - Invalid Template Syntax: Check HTML for Jinja2 syntax errors. Common issues include unclosed tags, mismatched quotes, or incorrect variable names. - Invalid JSON Schema: Validate your Input Schema using a JSON Schema validator. - Data Mismatch: Ensure AI agent is providing data that matches the schema structure. - Permission Issues: Verify the user has read permission on the widget.

Styling Issues

Symptoms: Widget appears unstyled or styles conflict with the page

Solutions: - Check CSS syntax for errors - Ensure you're using CSS variables for theme-aware styling - Remember that Shadow DOM isolates styles - external styles won't affect your widget - Test in both light and dark themes

Charts Not Initializing

Symptoms: Chart widget renders but chart doesn't appear

Solutions: - Verify isChart: true is set in the data object - Check that data-chart-type attribute is present on chart container - Ensure chart data structure matches Frappe Charts requirements - Check browser console for JavaScript errors

Preview vs. Live Rendering Differences

Symptoms: Widget looks different in preview than in actual chat

Solutions: - Ensure Preview Sample Data exactly matches the schema structure - Check for dependencies on real-time data that isn't in the sample - Verify widget doesn't rely on external context not available in preview

Symptoms: Widget is linked to agent but never gets invoked

Solutions: - Improve widget description to make its purpose clearer - Use more specific keywords in the description - Ensure widget is actually linked in the agent's Widgets child table - Check that agent has appropriate instructions to use visual output when relevant - Test with explicit requests (e.g., "show me a chart of...")

TM AI Chat Agent: Agents that can invoke widgets during conversations
TM AI Context: Provides background data that can be used in widget rendering
Frappe Charts: Chart library integrated for data visualization widgets
Shadow DOM: Web technology used to isolate widget styles and scripts

Technical Notes

Rendering Pipeline

AI agent calls widget as a function/tool with data payload
Server receives widget invocation with data
Server validates data against Input Schema
Server renders Template HTML with data using Jinja2
Rendered HTML + CSS returned to client
Client creates Shadow DOM container
HTML and CSS injected into Shadow DOM
If chart widget, Frappe Charts initialized
Widget displayed in chat interface

Shadow DOM Isolation

Widgets use Shadow DOM (Web Components standard) to: - Prevent CSS conflicts between widget and page - Isolate JavaScript execution - Enable component reusability - Support advanced features like charts without global dependencies

Jinja2 Support

Full Jinja2 template engine is available including: - Variables: {{ variable }} - Conditionals: {% if condition %} ... {% endif %} - Loops: {% for item in items %} ... {% endfor %} - Filters: {{ value | filter }} - Macros and imports (for complex widgets)

Available CSS Variables

Common theme variables available in widgets: - --card-bg: Card background color - --border-color: Border colors - --text-color: Primary text color - --text-muted: Muted/secondary text color - --primary-color: Brand primary color - --bg-color: Page background color - --shadow-sm, --shadow-md: Shadow values - --border-radius: Standard border radius

Last Updated: January 2026
Version: 1.0
Module: TechMaju AI

AI Chat Widget

TM AI Chat Widget

Understanding the TM AI Chat Widget DocType