SDK & Integrations

JavaScript SDK, iFrame embed, webhooks, and React component — integrate Clara AI into anything.

JavaScript / TypeScript SDK

The official clara-ai SDK works in Node.js and the browser. Install via npm or yarn.

bash

npm install @clara-ai/sdk
# or
yarn add @clara-ai/sdk

typescript

import { ClaraClient } from "@clara-ai/sdk";

const clara = new ClaraClient({
  apiKey: process.env.CLARA_API_KEY!,
  baseUrl: "https://your-org.clara.ai",
});

// Run a RAG search
const result = await clara.search({
  kbId: "kb_your_id",
  query: "What does my policy cover for water damage?",
  topK: 5,
});

console.log(result.answer);
console.log(result.citations);

iFrame Embed Reference

The simplest integration — one script tag, zero dependencies. Paste before </body> on any page.

html

<script
  src="https://your-org.clara.ai/embed/widget.js"
  data-org="your-org-slug"
  data-kb="kb_your_id"
  data-theme="dark"
  data-primary-color="#6366f1"
  data-position="bottom-right"
  data-voice="false"
  data-placeholder="Ask a question..."
  defer
></script>

Embed attributes

data-orgrequiredYour organisation slug (from Admin → Settings)

data-kbrequiredKnowledge base ID to query

data-themeoptional"dark" or "light" (default: dark)

data-primary-coloroptionalHex colour for the chat bubble and accents

data-positionoptional"bottom-right" or "bottom-left" (default: bottom-right)

data-voiceoptional"true" to show mic button (Starter+ only)

data-placeholderoptionalInput placeholder text

Webhooks & Events

Clara sends HTTP POST events to your endpoint for key lifecycle events. Configure your webhook URL in Admin → Settings → Webhooks.

json

// document.ingested event payload
{
  "event": "document.ingested",
  "org_id": "org_xxx",
  "data": {
    "document_id": "doc_xxx",
    "kb_id": "kb_xxx",
    "filename": "policy-2025.pdf",
    "chunk_count": 38,
    "status": "ready"
  },
  "timestamp": "2025-06-01T12:00:00Z"
}

document.ingested

document.failed

kb.created

kb.deleted

query.completed

subscription.changed

React Component

Import the pre-built React chat component for full control over styling and placement.

tsx

import { ClaraChat } from "@clara-ai/react";

export function SupportPage() {
  return (
    <div className="flex h-screen">
      <aside className="w-80">
        <ClaraChat
          apiKey={process.env.NEXT_PUBLIC_CLARA_KEY}
          kbId="kb_your_id"
          theme="dark"
          placeholder="Ask about your policy..."
          onCitation={(citation) => console.log(citation)}
        />
      </aside>
    </div>
  );
}

← API Reference View Pricing →