KriyaOS Chat Widget

Production-ready embeddable chat widget for websites and web apps.

Package: @kanhaiyamark/kriyaos-chat-widget

Features

• Lightweight ESM and CJS bundles
• Session persistence with localStorage
• Quick action chips for faster conversations
• Typing animation and streaming response support
• KriyaOS API support via workspaceId and agentId
• Works with plain HTML, React, and Next.js client components

Installation

Install from npm:

npm install @kanhaiyamark/kriyaos-chat-widget

Quick Start

To use the default chatbot launcher icon, place your GIF at public/assets/kriyaos-chat-wadget.gif. You can override it any time with theme.logoUrl.

Plain HTML / Vanilla JS

<script type="module">
  import ChatWidget from "@kanhaiyamark/kriyaos-chat-widget";

  ChatWidget.init({
    workspaceId: "your-workspace-id",
    agentId: "your-agent-id",
    title: "Support Assistant",
    theme: {
      primaryColor: "#0f766e",
      logoUrl: "https://app.kriyaos.com/favicon.ico",
      welcomeMessage: "Hi! Ask me anything.",
      fontSizeMode: "small"
    }
  });
</script>

React

import { useEffect } from "react";
import ChatWidget from "@kanhaiyamark/kriyaos-chat-widget";

export default function App() {
  useEffect(() => {
    ChatWidget.init({
      workspaceId: "your-workspace-id",
      agentId: "your-agent-id"
    });
  }, []);

  return null;
}

Next.js (App Router)

Use this only in a client component because the widget uses window, document, and localStorage.

"use client";

import { useEffect } from "react";
import ChatWidget from "@kanhaiyamark/kriyaos-chat-widget";

export default function ChatWidgetLoader() {
  useEffect(() => {
    ChatWidget.init({
      workspaceId: "your-workspace-id",
      agentId: "your-agent-id"
    });
  }, []);

  return null;
}

API

Call:

ChatWidget.init(config)

Config Reference

| Field | Type | Required | Description | |---|---|---|---| | workspaceId | string | Yes | KriyaOS workspace id | | agentId | string | Yes | KriyaOS agent id | | apiBaseUrl | string | No | Base URL for KriyaOS API | | headers | Record<string, string> | No | Additional request headers | | storageKey | string | No | Namespace seed for localStorage keys | | title | string | No | Header title in widget | | quickActions | string[] | No | Starter quick-action chips | | theme.primaryColor | string | No | Primary color (hex or gradient) | | theme.logoUrl | string | No | Logo URL shown in widget header | | theme.welcomeMessage | string | No | First assistant message | | theme.fontSizeMode | "small" | "medium" | "large" | No | UI text scaling |

You can get workspaceId and agentId from your KriyaOS workspace dashboard.

Request and Response Formats

KriyaOS format

Request body:

{
  "messages": [
    {
      "role": "user",
      "parts": [{ "type": "text", "text": "Hello" }]
    }
  ]
}

Expected response shape:

{
  "message": {
    "parts": [{ "type": "text", "text": "Hi, how can I help?" }]
  },
  "session": { "id": "session-id" }
}

Streaming (SSE) is supported using text/event-stream.

Production Notes

• Initialize the widget once per page load
• Always run in browser context only
• Configure CORS allow-list for your frontend origin
• Use HTTPS endpoints in production
• If your backend requires auth, pass headers in config

Troubleshooting

• CORS error in widget: allow your website origin on API side
• Nothing appears after install in Next.js: confirm component has "use client"
• Duplicate widgets: ensure init is called only once

License

MIT

Author

KriyaOS

Website: https://www.kriyaos.com/