Elaras/

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

OptionTypeRequiredDescription
chatbotKeystringYesYour public agent key (cbt_...)
apiUrlstringNoOverride 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:

EventFieldsDescription
deltacontent: stringNext token chunk from the AI
donemessage_id: number, credits_used: number, blocks?: Block[]Response complete. blocks is present when the agent returns structured UI components
errormessage: string, code?: stringAn 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.