Creating a Luzmo IQ Chat Component

In this guide, we'll show you how you can easily create an intelligent chat interface in your application, using Luzmo's IQ Chat component. The IQ Chat component enables natural language interactions with data, allowing your application's users to ask questions and receive insights through AI-powered responses (including multi-tenancy support ).

Whether you need a floating chat widget or a full-screen chat interface, this component can be easily adapted to your application's needs!

<luzmo-iq-embed-chat
  apiHost="https://api.luzmo.com/"
  appServer="https://app.luzmo.com/"
  authKey="< embed_authorization_key >"
  authToken="< embed_authorization_token >"
></luzmo-iq-embed-chat>

Before using the IQ Chat component, you must first install the relevant Luzmo embed library for your frontend framework, see the installation guide .

Chat vs Answer Component

Luzmo provides two distinct IQ components for different use cases:

IQ Chat Component

The Chat component provides a conversational interface designed for typical chat experiences where users can have ongoing dialogues with their data. It maintains conversation history and context throughout the chat session, making it perfect for exploratory data analysis.

By default, the Chat component will render in displayMode: "fullChat" , which allows you to create your own parent container for the chat window. If you'd like to provide a typical "Popup chat" experience, you can instead embed Luzmo IQ as a floating icon (that opens/closes a popup chat window) by setting the displayMode option to "chatWidget" .

<!-- Full chat component -->
<luzmo-iq-embed-chat
  options='{
    "displayMode": "fullChat"
  }'
></luzmo-iq-embed-chat>

<!-- Popup chat widget -->
<luzmo-iq-embed-chat
  options='{
    "displayMode": "chatWidget"
  }'
></luzmo-iq-embed-chat>

IQ Answer Component

The Answer component is typically used to extend the capabilities of an existing chat interface in your application, to allow it to render "Luzmo IQ"-specific responses (e.g. charts). For instance, your chat component may handle a wide range of conversations, while an LLM determines whether a prompt is data-related and should be routed through the Luzmo IQ API for a data-related response.

It can also be used outside of a chat context, e.g. to generate a text block or chart on a page based on a predetermined prompt (for example, an executive summary each time the page loads).

This allows you to create more customized chat experiences outside of the chat interface provided by the Chat component, but does require you to feed in your own chunks of data returned by the /message endpoint:

1. Use the /message endpoint to let Luzmo IQ handle data-related prompts

async function getLuzmoIQResponse(apiHost: string = "https://api.luzmo.com", embedKey: string, embedToken: string) {
  // Step 0: Base64 encode the Embed Authorization Key-token pair
  // See here for more details about the Embed Authorization request: https://developer.luzmo.com/guide/dashboard-embedding--generating-an-authorization-token
  const credentials = `${embedKey}:${embedToken}`;
  const encodedKeyTokenPair = btoa(credentials);

  // ID of the conversation you wish to continue. If empty a new conversation will be started.
  let conversationId: string | undefined;

  // Step 1: Send question to IQ API with response mode control
  const response = await fetch(apiHost + '/ai/v1/message', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${encodedKeyTokenPair}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "What are our top selling products?",
      conversation_id: conversationId,
      response_mode: "mixed",      // "mixed" (default: both text and/or chart responses), "text_only", or "chart_only"
      lang: "en",                  // Language Luzmo IQ should use to respond
      timezone: "Europe/Brussels"  // Timezone of the user
    })
  });

  // Store the "X-Conversation-Id" header value
  conversationId = response.headers.get("X-Conversation-Id");

  // The response will be a stream (see docs: https://api.luzmo.com/ai/docs/api-docs/#/default/post_message)
  // Note that this simplified implementation doesn't handle the streaming response
  const result = await response.json();

  // Transform the result into a set of IQMessages and pass them along to the Luzmo IQ Answer component
  // See here: https://developer.luzmo.com/guide/iq--answer-component-api#answer-component-api-reference
  return ...;
}

<luzmo-iq-embed-answer
  messages='[
    {
      "type": "humanMessage",
      "message": "Purchase value per month over time",
      "messageId": "29f150a7-d448-4a44-91e9-e381ebae6a71"
    },
    {
      "type": "systemMessage",
      "message": "The analysis of Purchase value over time reveals a notable trend. From July 2022 to August 2022, Purchase value substantially increased from 1725 to 4274 (all time high). This suggests a potential increase in demand for specific product(s).",
      "messageId": "daeb4f9e-5b94-4d7a-998a-55f709803abf"
    },
    {
      "type": "chartAnswer",
      "question": "Purchase value per month over time",
      "chart": {
        "type": "line-chart",
        ... // Some chart configuration like slots and options
      }
    }
  ]'
></luzmo-iq-embed-answer>

Response Modes

Configure how Luzmo IQ responds to user questions with three distinct response modes:

• mixed (Default): Luzmo IQ will generate both textual responses and charts, depending on the prompt.

• text : Luzmo IQ will only generate textual responses (useful for e.g. executive summaries).

• chart : Luzmo IQ will only generate charts, no textual responses.

  • This is somewhat similar to the AI Chart generator , except it can handle conversations and more complex & data-specific prompts (e.g. go through multiple phases, analyze actual source data, etc.). As a result, it might however take a bit longer to propose a chart!

<!-- responseMode can also be "mixed" (default) or "chart" -->
<luzmo-iq-embed-chat
  options='{
    "responseMode": "text"
  }'
></luzmo-iq-embed-chat>

Styling and Theming

There are two elements you'd typically want to style:

• The Chat component styles can be adapted by specifying CSS variables for the luzmo-iq-chat-component component. Typically these will need to be specified as "global" styles to ensure they can be picked up by Chat component.

• Any charts generated by Luzmo IQ can be styled by specifying a dashboard theme in the options property of the Chat component.

CSS Variables Customization

Customize the chat appearance using CSS variables:

<style>
  /* You can use "CSS variable forwarding" from your application, or specify static values */
  .luzmo-iq-chat-container luzmo-iq-chat-component {
    --luzmo-iq-background-color: var(--background-color-alt-1);
    --luzmo-iq-font-color: var(--font-color);
    --luzmo-iq-human-message-background: var(--primary);
    --luzmo-iq-human-message-color: var(--primary-inv);
    --luzmo-iq-system-message-background: var(--background-color-alt-2);
    --luzmo-iq-system-message-color: var(--font-color);
    --luzmo-iq-border-radius: 0.75rem;
    --luzmo-iq-chat-header-background: var(--background-color-alt-3);
    --luzmo-iq-chat-header-color: var(--font-color-active);
  }
</style>
<div class="luzmo-iq-chat-container">
  <luzmo-iq-embed-chat></luzmo-iq-embed-chat>
</div>

Chart Theming

Ensure the charts generated by Luzmo IQ are styled according to the specified chartTheme in the options property of the Chat component:

<!-- Reference dashboard theme ID -->
<luzmo-iq-embed-chat
  options='{
    "chartTheme": "< theme_uuid >"
  }'
></luzmo-iq-embed-chat>
<!-- Ad-hoc (partial) chart theme definition -->
<luzmo-iq-embed-chat
  options='{
    "chartTheme": {
      "itemsBackground": "#0e0e0e",
      "colors": [
        "red",
        "green",
        "blue",
        "yellow",
        "orange",
        "purple"
      ]
    }
  }'
></luzmo-iq-embed-chat>

Chat Customizations

You can further customize the chat experience in the options property of the Luzmo IQ Chat component, where you can specify e.g. different welcome messages, a custom disclaimer text, etc.

<luzmo-iq-embed-chat
  options='{
    "areWelcomeMessagesVisible": true,
    "welcomeMessages": [ ... ],
    "areInitialSuggestionsEnabled": true,
    "initialSuggestions": [ ... ],
    "isDisclaimerVisible": true,
    "disclaimerText": "..."
  }'
></luzmo-iq-embed-chat>

Welcome Messages

Set custom welcome messages to welcome and guide users:

{
  "areWelcomeMessagesVisible": true,
  "welcomeMessages": [
    {
      "message": "Welcome to your data assistant! 👋"
    },
    {
      "message": "I can help you analyze product sales data, create charts, and answer questions about your business metrics."
    }
  ]
}

Initial Suggestions

Provide helpful starter questions for users:

{
  "areInitialSuggestionsEnabled": true,
  "initialSuggestions": [
    {
      "title": "Weekly Revenue Trends 📈"
    },
    {
      "title": "Top Stores 👑"
    },
    {
      "title": "Product Performance 🏆"
    }
  ]
}

Disclaimers

Add important disclaimers about AI-generated content:

{
  "isDisclaimerVisible": true,
  "disclaimerText": "AI-powered insights. Please verify important business decisions with additional data sources."
}

Multi-lingual and Timezone Support

You can ensure Luzmo IQ will analyze and answer in a specific language by specifying the locale in the options property of the Chat component. This will also translate any UI elements inside the Chat component. Besides that, you can also specify the timezone that should be used to retrieve the data.

<luzmo-iq-embed-chat
  options='{
    "locale": "es",
    "timezone": "America/New_York",
    "welcomeMessages": [
      {
        "message": "¡Hola! Puedo ayudarte a analizar tus datos."
      }
    ],
    "disclaimerText": "Información generada por IA. Por favor, verifica las decisiones empresariales importantes con fuentes de datos adicionales."
  }'
></luzmo-iq-embed-chat>

Conversation ID for Debugging

Enable conversation ID visibility for debugging and support purposes. The conversation ID appears in the chat interface on the bottom and can be used to reference specific conversations.

<luzmo-iq-embed-chat
  options='{
    "isConversationIdVisible": true
  }'
></luzmo-iq-embed-chat>

Improving Luzmo IQ Responses

To enhance the quality and accuracy of your IQ Chat responses, consider implementing these optimization strategies:

• Ensure your dataset and column names are meaningful and descriptive (see this Academy article on how to finetune your Luzmo dataset)

• Add e.g. synonyms and business-specific terminology to your dataset and column descriptions

• Create predefined Aggregation formulas in your datasets to ensure Luzmo IQ can consistently answer questions that might require more complex calculations

• Add extra context to your Authorization token to indicate how Luzmo IQ should answer, or add e.g. user-specific or company-specific context

Master Prompt Configuration

When requesting an Embed Authorization token , you can use the iq property to provide additional context for how the LLM should respond. You can find some context examples in this Academy article .

const Luzmo = require('@luzmo/nodejs-sdk');
const client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >",
  host: "< Your API host, defaults to https://api.luzmo.com >"
});

const response = await client.create('authorization', {
  type: "embed",
  // ...
  iq: {
    context: `
      You are a business intelligence assistant for an e-commerce company.

      Context:
      - Our fiscal year starts in April
      - Revenue should be reported in USD
      - Always consider seasonal trends in retail data

      Response guidelines:
      - Provide actionable insights
      - Include confidence levels when appropriate
      - Suggest follow-up questions for deeper analysis
      - Use business terminology familiar to executives
    `
  }
});

Next Steps

Congratulations, you now have a customized AI data assistant you can provide to your end-users in your application! The following resources might be interesting to further explore:

• Explore live examples and demos to get inspiration from common Luzmo IQ use-cases

• Luzmo IQ Introduction guide for installation and setup instructions of the Luzmo IQ components

• IQ Chat Component API Reference for detailed configuration options of the Chat component

• Luzmo IQ API Documentation