Solutions

Platform

Marketplace

Resources

Let's talk

SDK DocumentationWorktual Chatbot SDK

Worktual Chatbot SDK

Server client and React chat widget for a Worktual chatbot.

@worktual_limited/chatbot

Overview

The subdomain and its knowledge base are created in My Account. Upload the PDF there. This SDK does not create a super domain, create a subdomain, or upload a document. My Account gives you the numeric subdomain_id, starting at 1000. Pass that number to chat and end session.

Both the server client and the widget call the gateway.

POST {WORKTUAL_API_URL}/chatbot
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: <one key for this action>
subdomain: 1000

The server uses the org access token. The widget uses an embed token minted outside this client. Do not point baseUrl or apiBase at the chatbot service port 8000.

Install

npm install @worktual_limited/chatbot react react-dom

Requires Node.js 18 or newer. react and react-dom are only required for the widget.

Environment

Put these on the server. Do not put the access token in frontend code.

WORKTUAL_ACCESS_TOKEN=the-org-access-token
WORKTUAL_API_URL=<gateway-url>
WORKTUAL_SUPER_DOMAIN=YOUR_SUPER_DOMAIN

WORKTUAL_API_URL is the gateway origin Worktual gives you. When it is omitted, the client uses the default gateway.

Chat from the server

import { WorktualClient } from "@worktual_limited/chatbot";

const client = new WorktualClient({
  accessToken: process.env.WORKTUAL_ACCESS_TOKEN!,
  superDomainId: process.env.WORKTUAL_SUPER_DOMAIN!,
  baseUrl: process.env.WORKTUAL_API_URL,
});

const shop = "1000";
const reply = await client.chat(shop, "What are your return policies?", "s1");
console.log(reply.answer, reply.citations);

const followUp = await client.chat(shop, "Summarize that in one sentence", reply.session_id);
await client.endSession(shop, followUp.session_id);

shop is the numeric subdomain_id from My Account. reply is { session_id, answer, citations, usage }. usage is the provider token total for that turn: prompt_tokens (prompt, history, tool schemas, and tool results), completion_tokens (answer, tool-call arguments, and thinking), reasoning_tokens (the thinking portion, already inside completion_tokens), and total_tokens (prompt_tokens plus completion_tokens). Reuse session_id for the next question. sessionId is required on every chat call. Shop credits stay one per successful turn.

A question sends:

{
  "action": "chat",
  "session_id": "s1",
  "query": "What are your return policies?",
  "tools": []
}

End the session

The widget does this when the panel closes. Call it from the server when you already have the session id.

await client.endSession(shop, reply.session_id);

{
  "action": "end_session",
  "session_id": "s1"
}

Widget

Pass an embed token to the page. This client does not mint that token.

import { WorktualChat } from "@worktual_limited/chatbot/ui";
import "@worktual_limited/chatbot/ui/styles.css";

export function SupportChat({ token }: { token: string }) {
  return (
    <WorktualChat
      token={token}
      superDomainId={process.env.NEXT_PUBLIC_SUPER_DOMAIN!}
      subDomainId="1000"
      apiBase={process.env.NEXT_PUBLIC_API_URL}
      name="Lola"
      subtitle="Conversational Assistant"
      poweredBy="Worktual"
      color="#000000"
      logoUrl="https://cdn.example.com/logo.png"
      greeting="Hi — how can I help you today?"
    />
  );
}

token, superDomainId, and subDomainId are required. subDomainId is the numeric subdomain_id from My Account. apiBase is the same gateway origin. When it is omitted, the widget uses the default gateway.

The widget creates session_id when the panel opens and sends chat for each visitor message. Closing the panel sends end_session for that same id. The answer it shows is answer, with citations when the gateway returns them.

Prop

Required

Purpose

token

yes

Embed token for the page

superDomainId

yes

Tenant id

subDomainId

yes

Numeric subdomain_id from My Account

apiBase

Gateway origin. Defaults to the Worktual gateway

name, subtitle, poweredBy

Header text. Defaults are Lola, Conversational Assistant, Worktual

greeting

First assistant message

color

Brand hex color

logoUrl

Header and avatar image

defaultOpen

Panel starts open. Default true

sttUrl

Optional speech-to-text URL. When omitted, the mic is not active

className

Extra CSS class

Server methods

Every method posts to /chatbot. Pass the numeric subdomain_id.

Method

Action

What it does

chat(subdomainId, message, sessionId, tools?)

chat

Asks a question. sessionId is required

endSession(subdomainId, sessionId)

end_session

Clears that session

The client creates one Idempotency-Key per action. If that HTTP call times out or the gateway returns 408, 429, 502, 503, or 504, the client retries once with the same key.

Errors

401 means the access token was rejected. 403 means the tenant is not allowed to call this API. 429 means the rate limit was hit. The error text can include X-Request-ID and X-RateLimit-Remaining when the gateway sends those headers.

In this document