@eloquentai/chat-sdk

React SDK for integrating Eloquent AI's chat functionality into your applications.

Prerequisites

• React 18 or higher (only for the React implementation)
• Node.js 18 or higher
• A modern browser that supports ES6+

Installation

# Using npm
npm install @eloquentai/chat-sdk

# Using yarn
yarn add @eloquentai/chat-sdk

# Using pnpm
pnpm add @eloquentai/chat-sdk

Quick Start

React Implementation

To use the SDK in a React application, import the Chat component from the SDK.

import { Chat } from "@eloquentai/chat-sdk";

function App() {
  return (
    <Chat
      // REQUIRED - Your Eloquent AI app ID
      appId="YOUR_APP_ID"
      // OPTIONAL - You can provide a unique id that should be used to identify the user
      userId={crypto.randomUUID()}
    />
  );
}

Don't forget to import the base styles once, somewhere in your app:

import "@eloquentai/chat-sdk/index.css";

Vanilla Implementation

To use the SDK in a vanilla environment, include the script tag in your HTML file and call renderChat.

<script src="https://unpkg.com/@eloquentai/chat-sdk"></script>

<div id="chat-container"></div>

<script>
  EloquentChatSDK.renderChat(document.getElementById("chat-container"), {
    // REQUIRED - Your Eloquent AI app ID
    appId: "YOUR_APP_ID",
    // OPTIONAL - You can provide a unique id that should be used to identify the user
    userId: crypto.randomUUID(),
  });
</script>

renderChat returns an unmount function you can call to remove the chat widget:

<script>
  const unmount = EloquentChatSDK.renderChat(
    document.getElementById("chat-container"),
    { appId: "YOUR_APP_ID" },
  );

  // Later, to remove the widget:
  unmount();
</script>

Features

• Floating chat widget — a launcher bubble plus chat window, rendered in an isolated iframe so host page styles never leak in or out.
• Real-time messaging — assistant replies stream in over a WebSocket connection (AWS AppSync), with automatic reconnect and a backup polling fallback if the socket drops.
• Conversation persistence — the active conversation is restored automatically (e.g. on page reload) via local storage.
• User identification — supports anonymous device-based identity as well as an optional external user ID and custom user metadata.
• Proactive/welcome messages — an optional message bubble can appear automatically to invite users to start a conversation.
• Chat ratings — users can rate a conversation after it's closed or escalated.
• Human handoff / escalation — the SDK recognizes when a conversation is escalated to a human agent and closes the AI chat session accordingly.
• Theming — customize bubble colors and legal text to match your brand.
• Mobile responsive — automatically adapts layout for mobile viewports.

Configuration

Chat component props

Chat interface options

Passed via the chatProps prop.

Theming

<Chat
  appId="YOUR_APP_ID"
  theme={{
    userBubbleColor: "#6f34b7",
    legalText: "Powered by Eloquent AI",
  }}
/>

Advanced usage

renderChat

Programmatically mount the chat widget into any DOM element — used internally by the vanilla/UMD build, but also available from the ES module for non-JSX setups:

import { renderChat } from "@eloquentai/chat-sdk";

const unmount = renderChat(document.getElementById("chat-container"), {
  appId: "YOUR_APP_ID",
});

ChatInterface

The chat window UI without the floating launcher bubble or iframe isolation, for embedding the chat directly into your own layout (e.g. a dedicated support page).

import { ChatInterface } from "@eloquentai/chat-sdk";

<ChatInterface
  isOpen
  closeButton={false}
  cleanChatButton
  messages={messages}
  onSendMessage={onSendMessage}
/>;

useRealtimeSocket

A lower-level hook for subscribing directly to the real-time conversation event stream, if you need custom message handling outside of the provided components.

import { useRealtimeSocket } from "@eloquentai/chat-sdk";

const { connect, disconnect, clearProcessedIds } = useRealtimeSocket({
  chatSettings,
  chatId,
  messages,
  onMessage: (response, chatId) => {
    /* handle incoming assistant message */
  },
  onCognition: (content) => {
    /* assistant is "thinking" */
  },
  onCognitionComplete: () => {},
  fetchHistory: async (chatId) => [],
});

Support

For issues, feature requests, or questions, please contact the Eloquent AI team.