Golia Chatbot

A customizable, draggable, embeddable AI chatbot widget that works with React, Vue.js, Angular, and vanilla JavaScript. Features real-time streaming responses (SSE), dark/light themes, persistent chat history, and 50+ configuration options.

Features

• Multi-Framework: Works in React, Vue.js, Angular, and vanilla JS via Web Components
• Real-time Streaming: See bot responses as they generate (Server-Sent Events)
• Drag & Drop: Drag the launcher button and chat window anywhere on screen
• Dark / Light Theme: Built-in theming with CSS variables
• Persistent History: Chat messages saved in localStorage
• Responsive: Mobile-friendly with optional full-screen mode
• RTL Support: Right-to-left language support
• Markdown: Rich message rendering (code blocks, tables, links, images)
• Quick Replies: Suggestion buttons for guided conversations
• Customizable: 50+ props for appearance, behavior, and callbacks
• TypeScript: Fully typed with .d.ts declarations

Installation

# npm
npm install golia-chatbot

# yarn
yarn add golia-chatbot

# pnpm
pnpm add golia-chatbot

Quick Start (React)

import React from "react";
import { GoliaBot, GoliaWidget } from "golia-chatbot";

function App() {
  const bot = new GoliaBot({
    name: "Golia",
    apiEndpoint: "https://your-api.com",
    apiKey: "your-api-key",
    greeting: "Hello! How can I help you?",
    user: { email: "[email protected]" },
  });

  return (
    <GoliaWidget
      bot={bot}
      position="bottom-right"
      primaryColor="#4F46E5"
      draggable={true}
      draggableChat={true}
      headerTitle="Golia Assistant"
      headerSubtitle="Online"
      showClearButton={true}
      showTimestamp={true}
      quickReplies={[
        { label: "What can you do?" },
        { label: "Help me", value: "I need help" },
      ]}
      footerText="Powered by Golia"
    />
  );
}

Usage in Vue.js

The package ships a <golia-chat> Web Component that works in Vue (and any other framework).

<template>
  <golia-chat
    bot-name="Golia"
    api-endpoint="https://your-api.com"
    api-key="your-api-key"
    user-email="[email protected]"
    greeting="Hello! How can I help you?"
    primary-color="#4F46E5"
    position="bottom-right"
    placeholder="Type a message..."
  />
</template>

<script>
// Import once to register the <golia-chat> custom element
import "golia-chatbot/dist/esm/index.js";

export default {
  name: "App",
};
</script>

Vue 3 Setup

If Vue warns about unknown custom elements, configure it:

// vite.config.js
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === "golia-chat",
        },
      },
    }),
  ],
});

Usage in Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from "@angular/core";
import "golia-chatbot";

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})
export class AppModule {}

<!-- app.component.html -->
<golia-chat
  bot-name="Golia"
  api-endpoint="https://your-api.com"
  api-key="your-api-key"
  user-email="[email protected]"
  primary-color="#4F46E5"
></golia-chat>

Usage in Vanilla JavaScript / HTML

<script src="https://unpkg.com/golia-chatbot/dist/esm/index.js" type="module"></script>

<golia-chat
  bot-name="Golia"
  api-endpoint="https://your-api.com"
  api-key="your-api-key"
  user-email="[email protected]"
  greeting="Hello! How can I help?"
  primary-color="#6366f1"
  position="bottom-right"
></golia-chat>

Programmatic Control (JavaScript)

<script type="module">
  import { GoliaBot } from "golia-chatbot";

  const bot = new GoliaBot({
    name: "Golia",
    apiEndpoint: "https://your-api.com",
    apiKey: "your-key",
    user: { email: "[email protected]" },
  });

  // Send a message programmatically
  const { promise, abort } = bot.processMessageStream("Hello!", "user1");
  const response = await promise;
  console.log(response);
</script>

GoliaBot Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | "Golia" | Bot display name | | greeting | string | "Salam, je suis Golia..." | Initial greeting message | | apiEndpoint | string | — | API base URL (required) | | apiKey | string | — | Bearer token for API auth | | user | object | — | User info (email, firstName, lastName, avatar) | | agent_name | string | "underground" | Agent identifier for the API | | session_id | string | — | Resume a previous session | | stream | boolean | true | Enable streaming responses | | customHeaders | Record<string, string> | {} | Extra HTTP headers | | timeout | number | 30000 | Request timeout in ms | | retryAttempts | number | 0 | Number of retries on failure | | retryDelay | number | 1000 | Delay between retries (ms) | | chatEndpointPath | string | "/chat" | API path appended to endpoint | | extraPayload | Record<string, unknown> | {} | Additional fields in request body | | onNewMessage | function | — | Callback when message is sent | | onStreamUpdate | function | — | Callback for each streaming chunk |

GoliaBot Methods

bot.getInitialGreeting(); // Get greeting text
bot.getBootName(); // Get bot name
bot.getSessionId(); // Get current session ID
bot.setSessionId(id); // Set session ID
bot.setGreeting(text); // Update greeting
bot.setName(name); // Update bot name
bot.setAgentName(name); // Update agent name
bot.setApiEndpoint(url); // Change API endpoint
bot.setApiKey(key); // Change API key
bot.setCustomHeaders({}); // Update headers
bot.setExtraPayload({}); // Update extra payload
bot.processMessageStream(msg, uid); // Send message (returns { promise, abort })
bot.destroy(); // Cleanup & abort

GoliaWidget Props (React)

Core

| Prop | Type | Default | Description | |------|------|---------|-------------| | bot | GoliaBot | required | Bot instance | | userId | string | "user1" | Unique user ID |

Theme & Appearance

| Prop | Type | Default | Description | |------|------|---------|-------------| | theme | "light" \| "dark" | "light" | Color theme | | primaryColor | string | "#4F46E5" | Primary brand color | | secondaryColor | string | — | Hover / accent color | | fontFamily | string | — | Custom font | | borderRadius | number | 12 | Container border radius (px) |

Logo & Branding

| Prop | Type | Default | Description | |------|------|---------|-------------| | launcherIcon | string \| ReactNode | Golia icon | Launcher button icon (URL or element) | | botAvatarUrl | string | Default SVG | Bot avatar in messages | | headerLogo | string \| ReactNode | Bot avatar | Header logo (URL or element) | | userAvatarUrl | string | — | User avatar in messages | | showBotAvatar | boolean | true | Show bot avatar | | showUserAvatar | boolean | false | Show user avatar | | launcherSize | number | 64 | Launcher button size (px) | | footerText | string | — | Footer text (e.g. "Powered by Golia") | | footerLink | string | — | Footer link URL |

Layout

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | "bottom-right" \| "bottom-left" \| "top-right" \| "top-left" | "bottom-right" | Widget position | | width | number | 380 | Chat container width (px) | | height | number | 600 | Chat container height (px) | | zIndex | number | 99999 | CSS z-index | | className | string | — | Additional CSS class | | rtl | boolean | false | Right-to-left layout | | fullScreenOnMobile | boolean | false | Full-screen on mobile |

Header

| Prop | Type | Default | Description | |------|------|---------|-------------| | showHeader | boolean | true | Show header bar | | headerTitle | string | Bot name | Custom title | | headerSubtitle | string | — | Subtitle (e.g. "Online") | | showCloseButton | boolean | true | Show close button | | showClearButton | boolean | false | Show clear history button |

Input

| Prop | Type | Default | Description | |------|------|---------|-------------| | placeholder | string | "Ecrivez votre message..." | Input placeholder | | inputMaxLength | number | 0 (unlimited) | Max characters | | sendOnEnter | boolean | true | Send on Enter key | | disableInput | boolean | false | Disable input | | textareaMode | boolean | false | Multi-line textarea | | textareaRows | number | 2 | Textarea rows |

Behavior

| Prop | Type | Default | Description | |------|------|---------|-------------| | defaultOpen | boolean | false | Open on mount | | autoOpenDelay | number | 0 | Auto-open after N ms | | draggable | boolean | true | Drag the launcher | | draggableChat | boolean | true | Drag the chat window (via header) | | dragBoundary | boolean | true | Keep within viewport when dragging | | showLauncherWhenOpen | boolean | true | Show launcher when chat is open | | closeOnClickOutside | boolean | true | Close on outside click | | persistSession | boolean | true | Save messages in localStorage | | maxHistoryMessages | number | 50 | Max persisted messages | | soundEnabled | boolean | false | Play notification sound | | soundUrl | string | — | Custom sound URL |

Messages

| Prop | Type | Default | Description | |------|------|---------|-------------| | showTimestamp | boolean | false | Show message timestamps | | timestampFormat | "time" \| "datetime" | "time" | Timestamp format | | showTypingIndicator | boolean | true | Show typing dots | | quickReplies | QuickReply[] | — | Suggestion buttons | | errorMessage | string | "Desole, une erreur..." | Error fallback message | | notificationCount | number | 0 | Badge count | | emptyStateText | string | — | Empty state message |

Inline Styles

| Prop | Type | Description | |------|------|-------------| | style | CSSProperties | Root widget styles | | containerStyle | CSSProperties | Chat container styles | | launcherStyle | CSSProperties | Launcher button styles | | messagesStyle | CSSProperties | Messages area styles | | inputStyle | CSSProperties | Input area styles |

Callbacks

| Prop | Type | Description | |------|------|-------------| | onOpen | () => void | Chat opened | | onClose | () => void | Chat closed | | onMessageSent | (message: string) => void | User sent a message | | onMessageReceived | (message: string) => void | Bot response complete | | onError | (error: Error) => void | Error occurred |

Web Component Attributes

When using <golia-chat> in Vue, Angular, or vanilla JS, configure via HTML attributes:

| Attribute | Description | |-----------|-------------| | bot-name | Bot display name | | api-endpoint | API base URL | | api-key | Bearer token | | user-id | User identifier | | user-email | User email (required with api-endpoint) | | user-first-name | User first name | | user-last-name | User last name | | user-avatar | User avatar URL | | placeholder | Input placeholder text | | primary-color | Primary theme color | | bot-avatar-url | Bot avatar URL | | greeting | Initial greeting message | | max-history-messages | Max persisted messages | | position | Widget position |

Web Component Methods

const chat = document.querySelector("golia-chat");
chat.open(); // Open the chat
chat.close(); // Close the chat
chat.clearHistory(); // Clear chat history
chat.sendMessage("Hello!"); // Send a message
chat.getBot(); // Get the GoliaBot instance

Web Component Events

const chat = document.querySelector("golia-chat");

chat.addEventListener("message-added", (e) => {
  console.log("New message:", e.detail.message);
});

chat.addEventListener("history-cleared", () => {
  console.log("History cleared");
});

chat.addEventListener("new-message", (e) => {
  console.log("Sent:", e.detail.message);
});

chat.addEventListener("stream-update", (e) => {
  console.log("Chunk:", e.detail.chunk);
});

Drag & Drop

Both the launcher button and the chat window are draggable by default:

<GoliaWidget
  bot={bot}
  draggable={true} // Drag the launcher button
  draggableChat={true} // Drag the chat window (via header)
  dragBoundary={true} // Keep within viewport bounds
/>

• Launcher: Click and drag the floating button to reposition it
• Chat Window: Click and drag the header bar to move the chat
• Click vs drag is automatically detected (3px threshold)
• Enable dragBoundary to prevent the widget from being dragged off-screen

Theming

Light / Dark Mode

<GoliaWidget bot={bot} theme="dark" primaryColor="#6366f1" />

CSS Variables

Override these CSS variables for full control:

.golia-widget {
  --golia-primary: #4361ee;
  --golia-primary-hover: #3a56d4;
  --golia-font: "Inter", sans-serif;
  --golia-border-radius: 12px;
  --golia-text: #333333;
  --golia-light-text: #6b7280;
  --golia-bg: #ffffff;
  --golia-message-bg: #f3f4f6;
  --golia-user-msg-bg: var(--golia-primary);
  --golia-user-msg-color: #ffffff;
  --golia-border: rgba(0, 0, 0, 0.08);
  --golia-input-bg: #f9fafb;
  --golia-code-bg: #1e1e2e;
  --golia-code-text: #e0e0e0;
}

Advanced Examples

Custom Launcher & Header

<GoliaWidget
  bot={bot}
  launcherIcon="https://example.com/my-icon.png"
  headerLogo="https://example.com/logo.png"
  headerTitle="Support"
  headerSubtitle="We reply instantly"
  showClearButton={true}
  showLauncherWhenOpen={false}
/>

Auto-Open with Quick Replies

<GoliaWidget
  bot={bot}
  autoOpenDelay={3000}
  quickReplies={[
    { label: "Pricing", value: "Tell me about pricing" },
    { label: "Demo", value: "I want a demo" },
    { label: "Support", value: "I need support" },
  ]}
/>

Multi-line Input with Timestamps

<GoliaWidget
  bot={bot}
  textareaMode={true}
  textareaRows={3}
  showTimestamp={true}
  timestampFormat="datetime"
/>

RTL Layout (Arabic / Hebrew)

<GoliaWidget
  bot={bot}
  rtl={true}
  placeholder="اكتب رسالتك..."
  headerTitle="مساعد"
/>

Full-Screen Mobile

<GoliaWidget
  bot={bot}
  fullScreenOnMobile={true}
  showLauncherWhenOpen={false}
/>

Custom API Configuration

const bot = new GoliaBot({
  name: "Support Bot",
  apiEndpoint: "https://api.example.com",
  apiKey: "sk-xxx",
  chatEndpointPath: "/v2/chat",
  customHeaders: { "X-Custom": "value" },
  extraPayload: { context: "support" },
  timeout: 60000,
  retryAttempts: 3,
  retryDelay: 2000,
});

API Reference

Exports

import {
  // React components
  GoliaBot, // Bot class (core, framework-agnostic)
  GoliaWidget, // React widget component
  GoliaIcon, // React SVG icon component
  GoliaWebComponent, // Web Component (Vue, Angular, vanilla JS)
  DEFAULT_BOT_AVATAR, // Base64 default avatar

  // Types
  GoliaBotOptions,
  StreamingResponse,
  GoliaWidgetProps,
  WidgetPosition,
  WidgetTheme,
  QuickReply,
} from "golia-chatbot";

License

MIT