Typed helpers for the dashboard HTTP API—agents, visitor chat, playground, ops, workflows—and how this differs from workflow webhooks.

TypeScript SDK (`@wisebotai/sdk`)

The TypeScript SDK wraps apps/web HTTP endpoints with typed helpers. Use it for Node or browser integrations instead of hand-rolling every fetch to /api/v1/… and /api/chat/agent.

Area	SDK module	Auth
Ops	`client.v1.status()`, `client.v1.activity.list()`	JWT or `wb_live_`
Agents	`client.agents.list()`, `client.agents.create()`	JWT or `wb_live_`
Visitor chat (SSE)	`client.chat.createSession()`, `client.chat.stream()`	JWT or `wb_live_`
Playground (async)	`client.playground.*`	JWT only
Workflows	`client.workflows.run(flowId)`	JWT or `wb_live_`
Knowledge	`client.knowledge.list()`, `upload()`, attach via `Tools.KnowledgeBase({ label })`	JWT or `wb_live_`
API keys / webhooks	`client.admin.apiKeys.`, `client.admin.webhooks.`	JWT only
Workflow webhooks	Not included	Triggering workflows

Workflow triggers use /workflows/trigger on the Convex site origin and a per-workflow secret; the SDK targets the web app origin. Keep those contexts separate.

Install and configuration

pnpm add @wisebotai/sdk

Option / env	Purpose
`baseUrl`	Web app origin (no path). Falls back to `WISEBOTAI_BASE_URL`.
`apiKey`	`Authorization: Bearer`: dashboard JWT or org API key (`wb_live_…`).
`authMode`	Optional: `"auto"` (default), `"jwt"`, or `"api_key"`.

Quick start

import { WisebotAI } from "@wisebotai/sdk";

const client = new WisebotAI({
  apiKey: process.env.WISEBOTAI_API_KEY ?? process.env.WISE_KEY!, // wb_live_… or dashboard JWT
  baseUrl: process.env.WISEBOTAI_BASE_URL,
});

Enterprise visitor chat (billable SSE)

const session = await client.chat.createSession({
  externalUserId: "user_42",
  agentId: "optional-agent-id",
});

for await (const event of client.chat.stream({
  prompt: "Hello!",
  threadId: session.threadId,
  contactSessionId: session.contactSessionId,
})) {
  if (event.type === "finish") console.log(event.fullText);
}

Resume an open session: GET /api/v1/chat/sessions?externalUserId= via client.chat.resumeSession({ externalUserId }).

Playground (JWT, async agent runs)

const pg = WisebotAI.forPlayground({
  accessToken: process.env.WISEBOT_ACCESS_TOKEN!,
  baseUrl: process.env.WISEBOTAI_BASE_URL,
});

const { session, run, text } = await pg.playground.chat({
  agentId: "…",
  message: "Summarize our refund policy",
});

const traces = await pg.playground.listTraces({ runId: run._id });

Playground methods: createSession, listSessions, resumeSession, sendMessage, getLatestRun, waitForRun, runTurn, chat, listTraces, stopRun, getPendingApproval, approveTool, denyTool, listMessages. (syncAgent is available for advanced playground agent switching.)

runTurn / chat accept optional autoApprove, attachmentIds, timeoutMs, and pollMs. chat.stream also accepts attachmentIds.

SDK/CLI playground sessions are billable and count toward your plan reply pool.

Ops parity with CLI

await client.v1.status();
await client.v1.activity.list({ limit: 20 });
const { agents } = await client.agents.list();

Workflows (dashboard API)

Run a workflow synchronously with your org JWT or wb_live_ API key:

const result = await client.workflows.run("<workflowId>", {
  inputs: { ticketId: "T-1" }, // keys match Input step field names
});
// POST /api/v1/flow/{workflowId} → { ok, runId, result, error }

This is not the Convex webhook (/workflows/trigger). Use workflow webhooks when you have a per-workflow secret and trigger from external systems without dashboard credentials. The dashboard API honors workflow IP allow/block lists.

Admin (JWT only)

await client.admin.apiKeys.list();
await client.admin.apiKeys.create({ label: "CI key" });
await client.admin.webhooks.create({
  url: "https://example.com/hooks/wisebot",
  events: ["conversation.resolved"],
});

Knowledge base (label-first — no file IDs required)

import { Tools } from "@wisebotai/sdk";

// Discover files by filename
const { files } = await client.knowledge.list({ limit: 25 });
console.log(files.map((f) => f.name));

// Upload programmatically
await client.knowledge.upload({
  file: pdfBlob,
  filename: "refund-policy.pdf",
  folderPath: "Legal",
});

// Attach by filename — server resolves label → entry id on create
await client.agents.create({
  name: "Support",
  model: "gpt-4o-mini",
  tools: [
    Tools.KnowledgeBase({ label: "refund-policy.pdf" }),
    Tools.Connector({ provider: "github" }), // MCP get_commit_history
  ],
});

Connect GitHub under Dashboard → Connectors before the agent can call get_commit_history.

`Agent` helper (agents-as-code)

import { Agent, Tools } from "@wisebotai/sdk";

const agent = await new Agent({
  name: "Docs bot",
  model: "gpt-4o-mini",
  tools: [Tools.KnowledgeBase({ label: "handbook.pdf" })],
  apiKey: process.env.WISE_KEY,
  baseUrl: process.env.WISEBOTAI_BASE_URL,
}).deploy();

`Tools`

Tools.ImageSearch(), Tools.KnowledgeBase({ label: "filename.pdf" }), Tools.Calendar()
Tools.Function({ name, description, parameters }) — custom tools
Tools.Connector({ provider: "github" | "stripe" | "linear" }) — MCP stubs; connect providers in the dashboard

The optional memory field on agent create is accepted for compatibility; conversation context is thread-scoped via chat sessions, not stored on the agent row.

Errors

WisebotConfigurationError — Missing baseUrl / apiKey.
WisebotAuthError — Wrong credential type (e.g. API key on JWT-only playground/admin).
WisebotApiError — Non-2xx HTTP response.

TypeScript SDK (@wisebotai/sdk)