JavaScript SDK
@elaras/chat-sdk is the browser-side SDK for building custom chat UIs. Framework-agnostic — use it directly in vanilla JS, React, Vue, Svelte, or anything else.
Use this SDK when you want a completely custom chat UI without the widget — your own design, your own layout, full control.
Setup
Option A — npm install (modern bundlers)
npm install @elaras/chat-sdk
import { ChatClient, renderBlocks } from '@elaras/chat-sdk'; import '@elaras/chat-sdk/blocks.css';
Option B — script tag (no bundler)
<script src="https://ask-api.elaras.ai/sdk/sdk.js"></script> <link rel="stylesheet" href="https://ask-api.elaras.ai/sdk/blocks.css">
This exposes window.ElarasSDK with ChatClient, renderBlock, and renderBlocks.
Creating a client
const { ChatClient } = window.ElarasSDK const client = new ChatClient({ chatbotKey: 'cbt_your_key_here' })
Options
| Option | Type | Required | Description |
|---|---|---|---|
chatbotKey | string | Yes | Your public agent key (cbt_...) |
apiUrl | string | No | Override the API base URL. Defaults to https://ask-api.elaras.ai |
Sessions
Anonymous sessions
The simplest way to create a session — a UUID is generated in the browser and stored in localStorage. No server-side work required.
const sessionId = client.getOrCreateSessionId()
The session ID persists across page reloads. Use clearSessionId() to force a fresh session (e.g. on sign-out).
Authenticated sessions
If your users are logged in, create the session server-side so you can attach their identity. This lets your skills receive a verified external_user_id on every message — useful for subscription checks, account lookups, and access control.
1. Create the session on your server
Call the Sessions API from your backend using your secret key:
// Your server (Node example) const res = await fetch('https://ask-api.elaras.ai/api/developer/v1/sessions', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.ELARAS_SECRET_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ chatbot_id: 'your-agent-id', external_user_id: currentUser.id, // your user's ID }), }) const { data } = await res.json() const sessionToken = data.id
The call is idempotent — passing the same external_user_id returns the same session, so you can call it on every page load without creating duplicate sessions.
2. Pass the token to the SDK
Return sessionToken to your frontend and use it directly — skip getOrCreateSessionId():
const client = new ChatClient({ chatbotKey: 'cbt_your_key_here' }) // sessionToken comes from your server const sessionId = sessionToken for await (const event of client.stream(sessionId, message)) { // ... }
3. Gate access in a skill
Your skills receive the identity on every call under session.external:
// Your skill endpoint app.post('/my-skill', (req, res) => { const { session } = req.body const userId = session.external?.user_id const user = db.users.find(userId) if (!user?.isSubscribed) { return res.json({ error: 'Your subscription has expired. Renew at example.com/billing to continue.' }) } // proceed with the skill })
The AI relays the error message to the user naturally. If the user renews and sends another message, the next skill call passes automatically — no session reset needed.
Methods
getOrCreateSessionId()
Returns the current session UUID from localStorage, or generates a new one if none exists. Use this for anonymous (unauthenticated) sessions.
const sessionId = client.getOrCreateSessionId() // e.g. "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
The session ID persists in localStorage across page reloads. For authenticated users, create the session server-side instead — see Authenticated sessions above.
stream(sessionId, message)
Sends a message and yields streaming events as the AI responds.
for await (const event of client.stream(sessionId, 'What are your opening hours?')) { if (event.type === 'delta') { appendToken(event.content) } else if (event.type === 'done') { if (event.blocks?.length) { renderBlocks(messagesEl, event.blocks, (text) => client.stream(sessionId, text)) } } }
Event types:
| Event | Fields | Description |
|---|---|---|
delta | content: string | Next token chunk from the AI |
done | message_id: number, credits_used: number, blocks?: Block[] | Response complete. blocks is present when the agent returns structured UI components |
error | message: string, code?: string | An error occurred |
send(sessionId, message)
Sends a message and waits for the complete response (no streaming).
const result = await client.send(sessionId, 'What are your prices?') console.log(result.response)
Returns: { message_id, response, credits_used, blocks? }
getConfig()
Fetches the agent's public configuration — name, greeting, appearance settings.
const config = await client.getConfig() console.log(config.greeting_message) // "Hi! How can I help?" console.log(config.appearance?.primary_color) // "#00C4A7"
getSession(sessionId)
Fetches the session and its full message history.
const session = await client.getSession(sessionId) for (const msg of session.messages) { appendMessage(msg.role, msg.content) }
clearSession(sessionId)
Deletes all messages in the session on the server. The session UUID remains valid.
await client.clearSession(sessionId)
clearSessionId()
Removes the session UUID from localStorage so the next call generates a fresh one.
client.clearSessionId()
submitTriage(sessionId, answers)
Submits answers to pre-chat triage questions before the first message is sent.
await client.submitTriage(sessionId, [ { question_id: 'name', answer: 'Jordan' }, { question_id: 'email', answer: 'jordan@example.com' }, ])
submitLead(sessionId, lead)
Associates an email address (and optional name) with the session.
await client.submitLead(sessionId, { email: 'user@example.com', name: 'Jordan' })
submitFeedback(messageId, rating)
Records thumbs-up or thumbs-down feedback for an AI response.
await client.submitFeedback(42, 'up')
Full example
A complete working chat UI in a single HTML file — no build step, no npm. Copy it, swap in your agent key, and open it in a browser.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>My Chat</title> <link rel="stylesheet" href="https://ask-api.elaras.ai/sdk/blocks.css"> <script src="https://ask-api.elaras.ai/sdk/sdk.js"></script> <style> * { box-sizing: border-box; margin: 0; padding: 0; } body { font-family: system-ui, sans-serif; display: flex; flex-direction: column; height: 100vh; } #messages { flex: 1; overflow-y: auto; padding: 16px; display: flex; flex-direction: column; gap: 8px; } .msg { max-width: 75%; padding: 10px 14px; border-radius: 16px; line-height: 1.5; } .msg--user { align-self: flex-end; background: #00C4A7; color: #fff; border-bottom-right-radius: 4px; } .msg--assistant { align-self: flex-start; background: #f0f0f0; color: #111; border-bottom-left-radius: 4px; } #form { display: flex; gap: 8px; padding: 12px; border-top: 1px solid #e5e5e5; } #input { flex: 1; padding: 10px 14px; border: 1px solid #e5e5e5; border-radius: 8px; font-size: 14px; } #send { padding: 10px 20px; background: #00C4A7; color: #fff; border: none; border-radius: 8px; cursor: pointer; font-size: 14px; } #send:disabled { opacity: 0.5; cursor: default; } </style> </head> <body> <div id="messages"></div> <form id="form"> <input id="input" type="text" placeholder="Ask something…" autocomplete="off"> <button id="send" type="submit">Send</button> </form> <script> const { ChatClient, renderBlocks } = window.ElarasSDK const CHATBOT_KEY = 'cbt_your_key_here' const client = new ChatClient({ chatbotKey: CHATBOT_KEY }) const sessionId = client.getOrCreateSessionId() const messagesEl = document.getElementById('messages') const inputEl = document.getElementById('input') const sendBtn = document.getElementById('send') const form = document.getElementById('form') function appendMessage(role, content) { const el = document.createElement('div') el.className = `msg msg--${role}` el.textContent = content messagesEl.appendChild(el) scrollToBottom() return el } function scrollToBottom() { messagesEl.scrollTop = messagesEl.scrollHeight } // Re-scroll when card images finish loading messagesEl.addEventListener('elaras:imageload', scrollToBottom) // Load history on mount const session = await client.getSession(sessionId) for (const msg of session.messages) { appendMessage(msg.role, msg.content) } form.addEventListener('submit', async (e) => { e.preventDefault() const text = inputEl.value.trim() if (!text) return inputEl.value = '' sendBtn.disabled = true appendMessage('user', text) const aiEl = appendMessage('assistant', '') for await (const event of client.stream(sessionId, text)) { if (event.type === 'delta') { aiEl.textContent += event.content scrollToBottom() } else if (event.type === 'done' && event.blocks?.length) { renderBlocks(messagesEl, event.blocks, (reply) => { inputEl.value = reply form.dispatchEvent(new Event('submit')) }) } else if (event.type === 'error') { aiEl.textContent = 'Something went wrong. Please try again.' } } sendBtn.disabled = false inputEl.focus() }) </script> </body> </html>
Swap cbt_your_key_here for your agent's public key (find it in the Embed tab). The sdk.js tag must appear before the inline <script> block — placing it at the top of <body> or in <head> with defer both work.
Error handling
SDK methods throw a standard Error on failure. The message property contains a human-readable description.
try { const result = await client.send(sessionId, 'Hello') } catch (err) { console.error(err.message) }
Block rendering
See Blocks for the full reference — all block types, specs, and theming.
