@irisidea/kalrav-ai

Kalrav.ai Agent Widget

Bring your AI agent directly into your website or app with a polished, embeddable chat widget.

Kalrav.ai helps businesses turn their knowledge, products, workflows, and customer conversations into always-available AI agents. Use it for support, ecommerce discovery, lead capture, product guidance, internal tools, onboarding, and custom agent experiences.

This package is the frontend runtime for placing a Kalrav agent anywhere: React, Next.js, Vue, Angular, or plain JavaScript.

What Kalrav.ai Does

Kalrav.ai gives teams the building blocks to launch AI agents that can:

• Answer customer questions from configured knowledge.
• Guide shoppers through products, categories, carts, and offers.
• Capture leads and qualify user intent.
• Support multilingual conversations.
• Handle file, audio, speech, feedback, downloads, and conversation history.
• Match your brand with custom colors, logo, font, welcome text, disclaimers, and controls.
• Render different agent experiences from the same widget runtime, such as default support, ecommerce, CRM, or lead-generation flows.

The goal is simple: your users should not have to search through pages, forms, or support queues. They can ask, choose, compare, and continue the journey inside the widget.

Why Use This Package

• One embeddable widget for many frontend frameworks.
• Works with Kalrav-hosted APIs out of the box.
• Also works with your own settings API and chat/query API.
• Supports custom payload and response mapping.
• Can render default chat UI, ecommerce UI, or generic future agent sections.
• Shows a default setup UI even before credentials are configured.
• Keeps agent-specific UI as conditional rendering, not a separate widget shell.

Install

npm install @irisidea/kalrav-ai

Quick Start With Kalrav.ai

import { KalravWidget } from "@irisidea/kalrav-ai/react";

export default function App() {
  return (
    <KalravWidget
      agentId="agent_xxx"
      apiKey="key_xxx"
    />
  );
}

With agentId and apiKey, the widget uses the default Kalrav.ai flow: it fetches your agent UI settings and connects to the Kalrav chat runtime.

If your app uses different APIs, you can provide your own settings endpoint, chat endpoint, request mapper, and response mapper. If you do not want the widget to fetch settings at all, you can configure the UI directly in code with agentUiSettings and agentUiData.

GA4 Analytics

Widget usage analytics are sent to Kalrav's GA4 property automatically through the package_analytic event. Events include package_analytic_name, agent_id, page information, conversation identity, and widget version. You can pass your logged-in user ID so events also include a stable kalrav_user_id.

When the widget bubble appears, the package also tracks page analytics for traditional pages and single-page apps. Client-side route changes from React, Next.js, Vue, Angular, or vanilla History API navigation are tracked automatically.

Tracked analytic names include pkg_page_view, pkg_page_engagement_duration, pkg_agent_widget_view, pkg_chat_widget_open, pkg_widget_session_duration, pkg_widget_closed, pkg_chat_started, pkg_chat_ended, pkg_conversation_abandoned, pkg_chat_message_sent, pkg_agent_response_received, and pkg_chat_feedback_submitted.

<KalravWidget
  agentId="agent_xxx"
  apiKey="key_xxx"
  analyticsUserId="user_123"
/>

Try The Widget Before Backend Setup

import { KalravWidget } from "@irisidea/kalrav-ai/react";

export default function App() {
  return <KalravWidget />;
}

The widget still renders with default settings. If a user tries to chat, it shows an in-widget message asking them to configure the agent ID and API key.

Ecommerce Agent UI

Kalrav can render ecommerce experiences inside the same chat widget. You can show product rows, category/menu pills, quick links, recently viewed products, and structured product results from chat responses.

Specialized rendering is enabled only by the widget's agentType configuration; it is not inferred from the UI-settings API response. If agentType is omitted, the normal query-agent view is rendered.

<KalravWidget
  agentType="ecommerce"
  agentUiData={{
    settings: {
      trending_enabled: true,
      trending_product_count: 5,
      menu_enabled: true,
      quick_links_enabled: true,
      recently_viewed_enabled: true,
      recently_viewed_count: 12
    },
    products: [
      {
        title: "Hunter Queen Size Bed",
        price: "₹9,999",
        image: "https://example.com/bed.png",
        url: "https://example.com/product"
      }
    ],
    categories: [
      { label: "Catalog" },
      { label: "Orders" },
      { label: "Cart" },
      { label: "Offers" },
      { label: "Help" }
    ],
    quick_links: [
      { label: "Door Mats", url: "/door-mats" }
    ]
  }}
/>

Bring Your Own APIs

You can keep using your own backend while using Kalrav’s widget UI.

<KalravWidget
  agentId="my-agent"
  apiKey="optional-key"
  chatApiBaseUrl="https://chat-api.example.com"
  centralSystemBaseUrl="https://agent-api.example.com"
  agentUiSettingsUrl="https://api.example.com/widget-settings/:agentId"
  queryUrl="https://api.example.com/chat"
  queryRequestMapper={({ query, sessionId }) => ({
    message: query,
    session_id: sessionId
  })}
  queryResponseMapper={(res) => ({
    response: res.answer,
    session_id: res.sessionId,
    user_id: res.userId,
    structured_data: res.structuredData
  })}
/>

queryUrl overrides only message queries. Use chatApiBaseUrl to change the built-in query, upload, and conversation-history service together. Use centralSystemBaseUrl to change built-in agent UI, ecommerce, allowed-pages, lead, feedback, and email-history requests. These are runtime props, so your app can change API environments without publishing a new widget package.

Automatic Chat History Email

You can configure the widget to email the current chat history automatically when the user closes the widget, starts a new chat, or both.

React and framework usage:

<KalravWidget
  agentId="agent_xxx"
  apiKey="key_xxx"
  emailChatAutoSendEnabled={true}
  emailChatAutoSendTo="support@example.com"
  emailChatAutoSendOnClose={true}
  emailChatAutoSendOnNewSession={true}
/>

Agent settings API usage:

{
  "email_chat_auto_send_enabled": true,
  "email_chat_auto_send_to": "support@example.com",
  "email_chat_auto_send_on_close": true,
  "email_chat_auto_send_on_new_session": true
}

The widget sends the current session history only when there is an active session with at least one user or bot message. It also prevents duplicate auto-emails for the same session, recipient, and unchanged message content. To test it, send a message first, wait for the chat session to be created, then close the widget or confirm a new chat.

This makes the widget flexible for teams that already have their own:

• Agent settings service
• Chat/query endpoint
• Ecommerce product API
• CRM or lead workflow API
• Custom authentication layer

Generic Agent UI Sections

Future agent types can provide generic UI sections without changing the widget runtime.

<KalravWidget
  agentType="crm"
  agentUiData={{
    sections: [
      {
        type: "pills",
        title: "Actions",
        items: [
          { label: "Create Lead" },
          { label: "Book Demo", url: "/demo" }
        ]
      },
      {
        type: "products",
        title: "Plans",
        items: [
          { title: "Starter", price: "$49", image: "/starter.png", url: "/starter" }
        ]
      }
    ]
  }}
/>

Framework Support

• React
• Next.js
• Vue
• Angular
• Vanilla JavaScript
• TypeScript

Learn More

Visit kalrav.ai to learn how Kalrav helps businesses build AI agents for support, ecommerce, lead generation, and workflow automation.