JavaScript SDK

The Ansa SDK provides a type-safe way to interact with the Ansa API from Node.js, browsers, or any JavaScript runtime. It includes both an API client for server-side integrations and helper functions for controlling the widget.

Installation

npm install @ansa/sdk

Quick Start

API Client

Use AnsaClient for server-side API access:

import { AnsaClient } from "@ansa/sdk";

const ansa = new AnsaClient({
  apiKey: process.env.ANSA_API_KEY!,
});

// Send a message and get a response
const response = await ansa.chat("agent_abc123", "What are your hours?");
console.log(response.message);

Use the widget helpers for client-side control:

import { embedWidget, openWidget, identify } from "@ansa/sdk";

// Embed the widget (alternative to script tag)
embedWidget({
  agentId: "agent_abc123",
});

// Identify the logged-in user
identify({
  userId: "user_456",
  userMetadata: {
    name: "Jane Smith",
    email: "[email protected]",
  },
});

// Open the chat when user clicks a button
document.getElementById("help-btn")?.addEventListener("click", () => {
  openWidget("I need help with my account");
});

API Client Reference

Configuration

interface AnsaConfig {
  /** Your Ansa API key (required) */
  apiKey: string;
  /** API base URL (default: https://api.ansa.so) */
  baseUrl?: string;
  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;
}

Create a client:

import { AnsaClient, createClient } from "@ansa/sdk";

// Using constructor
const ansa = new AnsaClient({
  apiKey: "ansa_sk_...",
  timeout: 60000, // 60 second timeout
});

// Using factory function
const ansa = createClient({
  apiKey: "ansa_sk_...",
});

Chat Methods

`chat(agentId, message, options?)`

Send a message and receive a complete response.

const response = await ansa.chat("agent_id", "Hello!", {
  conversationId: "conv_123", // Continue existing conversation
  metadata: {
    source: "mobile-app",
    userId: "user_456",
  },
});

console.log(response.message);        // "Hi! How can I help?"
console.log(response.conversationId); // "conv_789"
console.log(response.messageId);      // "msg_abc"
console.log(response.toolCalls);      // [{ id, name, args, result }]

Options:

Property	Type	Description
`conversationId`	`string`	Continue an existing conversation
`metadata`	`Record<string, unknown>`	Visitor metadata passed to the agent

Response:

Property	Type	Description
`message`	`string`	The agent’s response text
`conversationId`	`string`	Conversation ID for follow-ups
`messageId`	`string`	Unique message identifier
`toolCalls`	`ToolCall[]`	Tools executed during response

`chatStream(agentId, message, callbacks, options?)`

Stream responses token-by-token for real-time display.

await ansa.chatStream(
  "agent_id",
  "Explain quantum computing",
  {
    onToken: (token) => {
      // Append each token as it arrives
      process.stdout.write(token);
    },
    onToolCall: (toolCall) => {
      console.log(`Tool called: ${toolCall.name}`);
    },
    onMessage: (response) => {
      // Full response when complete
      console.log("\n\nFull message:", response.message);
    },
    onError: (error) => {
      console.error("Stream error:", error);
    },
    onComplete: () => {
      console.log("Stream finished");
    },
  },
  { conversationId: "conv_123" }
);

Callbacks:

Callback	Parameters	Description
`onToken`	`(token: string)`	Called for each streamed token
`onToolCall`	`(toolCall: ToolCall)`	Called when a tool is executed
`onMessage`	`(response: ChatResponse)`	Called with complete response
`onError`	`(error: Error)`	Called on stream error
`onComplete`	`()`	Called when stream ends

Agent Methods

`getAgents()`

List all agents in your organization.

const agents = await ansa.getAgents();

for (const agent of agents) {
  console.log(`${agent.name} (${agent.id})`);
  console.log(`  Model: ${agent.model}`);
  console.log(`  Temperature: ${agent.temperature}`);
}

`getAgent(agentId)`

Get details for a specific agent.

const agent = await ansa.getAgent("agent_abc123");

console.log(agent.name);         // "Sales Assistant"
console.log(agent.systemPrompt); // "You are a helpful..."
console.log(agent.model);        // "gpt-4o"

Agent Object:

Property	Type	Description
`id`	`string`	Unique agent identifier
`name`	`string`	Agent display name
`systemPrompt`	`string`	System prompt/instructions
`model`	`string`	AI model (e.g., “gpt-4o”)
`temperature`	`number`	Response randomness (0-1)
`createdAt`	`string`	ISO timestamp
`updatedAt`	`string`	ISO timestamp

Conversation Methods

`getConversations(agentId)`

List all conversations for an agent.

const conversations = await ansa.getConversations("agent_abc123");

for (const conv of conversations) {
  console.log(`${conv.id}: ${conv.messages.length} messages`);
}

`getConversation(conversationId)`

Get a conversation with its full message history.

const conversation = await ansa.getConversation("conv_xyz789");

for (const message of conversation.messages) {
  console.log(`${message.role}: ${message.content}`);
}

Conversation Object:

Property	Type	Description
`id`	`string`	Conversation identifier
`agentId`	`string`	Associated agent ID
`messages`	`Message[]`	Array of messages
`createdAt`	`string`	ISO timestamp
`updatedAt`	`string`	ISO timestamp

These functions control the embedded widget from your application code. They automatically queue commands if the widget isn’t ready yet.

`embedWidget(config)`

Programmatically embed the widget (alternative to the script tag).

import { embedWidget } from "@ansa/sdk";

embedWidget({
  agentId: "agent_abc123",
  apiUrl: "https://api.ansa.so",      // optional
  widgetUrl: "https://widget.ansa.so", // optional
});

`openWidget(message?)`

Open the chat widget, optionally with a pre-filled message.

import { openWidget } from "@ansa/sdk";

// Just open
openWidget();

// Open with message
openWidget("I'd like to schedule a demo");

`closeWidget()`

Close the chat widget.

import { closeWidget } from "@ansa/sdk";

closeWidget();

`toggleWidget()`

Toggle the widget open/closed.

import { toggleWidget } from "@ansa/sdk";

toggleWidget();

`isWidgetOpen()` / `isWidgetReady()`

Check widget state.

import { isWidgetOpen, isWidgetReady } from "@ansa/sdk";

if (isWidgetReady() && !isWidgetOpen()) {
  openWidget();
}

`showBubbles(messages, duration?)`

Show notification bubbles near the widget button.

import { showBubbles, hideBubbles } from "@ansa/sdk";

// Single message
showBubbles("Need help?");

// Multiple messages (appear sequentially)
showBubbles(["👋 Welcome!", "Ask me anything"], 10);

// Hide bubbles
hideBubbles();

`showForm(form, options?)`

Display a form in the widget. See Triggering Forms for details.

import { showForm } from "@ansa/sdk";

// Server-side form by name
showForm("contact_form");

// Client-side form with schema
showForm(
  {
    fields: [
      { name: "email", label: "Email", type: "email" },
      { name: "message", label: "Message", type: "textarea" },
    ],
    submitButtonText: "Send",
  },
  {
    onSubmit: (data) => console.log("Form submitted:", data),
    onCancel: () => console.log("Form cancelled"),
    sendToAgent: true, // Also send as chat message
  }
);

`identify(identity)` / `clearIdentity()`

Set or clear user identity. Identity is used for:

Form pre-filling — Fields automatically populate from userMetadata
HTTP tool authentication — Pass tokens to your APIs via {{userMetadata.token}} syntax
Personalization — Agent receives user context for personalized responses

See Identity for details.

import { identify, clearIdentity } from "@ansa/sdk";

// On login - include auth token for API calls
identify({
  userId: "user_123",
  userMetadata: {
    name: "Jane Smith",
    email: "[email protected]",
    plan: "pro",
    authToken: "eyJhbG...",  // Passed to HTTP tools via {{userMetadata.authToken}}
  },
});

// On logout
clearIdentity();

`getVisitorId()`

Get the anonymous visitor ID.

import { getVisitorId } from "@ansa/sdk";

const visitorId = getVisitorId();
// "v_1703347200000_abc123def"

`triggerEvent(eventName, data?)`

Fire a custom event for trigger automation.

import { triggerEvent } from "@ansa/sdk";

// Trigger when user views pricing
triggerEvent("viewed_pricing", {
  plan: "enterprise",
  source: "navbar",
});

Error Handling

The SDK throws AnsaError for API errors:

import { AnsaClient, AnsaError } from "@ansa/sdk";

const ansa = new AnsaClient({ apiKey: "..." });

try {
  await ansa.chat("invalid_agent", "Hello");
} catch (error) {
  if (error instanceof AnsaError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Code: ${error.code}`);
  }
}

AnsaError Properties:

Property	Type	Description
`message`	`string`	Human-readable error message
`statusCode`	`number`	HTTP status code
`code`	`string?`	Machine-readable error code

TypeScript

The SDK is written in TypeScript and exports all types:

import type {
  AnsaConfig,
  Agent,
  Message,
  ChatOptions,
  ChatResponse,
  ToolCall,
  Conversation,
  StreamCallbacks,
  FormSchema,
  FormField,
  ShowFormOptions,
} from "@ansa/sdk";

Getting Started

User Guides

Use Cases

Developer Guides

Tools & Forms

Integrations

API Reference

Support

JavaScript SDK

Installation

Quick Start

API Client

Widget Control

API Client Reference

Configuration

Chat Methods

`chat(agentId, message, options?)`

`chatStream(agentId, message, callbacks, options?)`

Agent Methods

`getAgents()`

`getAgent(agentId)`

Conversation Methods

`getConversations(agentId)`

`getConversation(conversationId)`

Widget Functions

`embedWidget(config)`

`openWidget(message?)`

`closeWidget()`

`toggleWidget()`

`isWidgetOpen()` / `isWidgetReady()`

`showBubbles(messages, duration?)`

`showForm(form, options?)`

`identify(identity)` / `clearIdentity()`

`getVisitorId()`

`triggerEvent(eventName, data?)`

Error Handling

TypeScript

Next Steps

Widget API

Triggering Forms

Getting Started

User Guides

Use Cases

Developer Guides

Tools & Forms

Integrations

API Reference

Support

​Installation

​Quick Start

​API Client

​Widget Control

​API Client Reference

​Configuration

​Chat Methods

​chat(agentId, message, options?)

​chatStream(agentId, message, callbacks, options?)

​Agent Methods

​getAgents()

​getAgent(agentId)

​Conversation Methods

​getConversations(agentId)

​getConversation(conversationId)

​Widget Functions

​embedWidget(config)

​openWidget(message?)

​closeWidget()

​toggleWidget()

​isWidgetOpen() / isWidgetReady()

​showBubbles(messages, duration?)

​showForm(form, options?)

​identify(identity) / clearIdentity()

​getVisitorId()

​triggerEvent(eventName, data?)

​Error Handling

​TypeScript

​Next Steps

Widget API

Triggering Forms

Installation

Quick Start

API Client

Widget Control

API Client Reference

Configuration

Chat Methods

`chat(agentId, message, options?)`

`chatStream(agentId, message, callbacks, options?)`

Agent Methods

`getAgents()`

`getAgent(agentId)`

Conversation Methods

`getConversations(agentId)`

`getConversation(conversationId)`

Widget Functions

`embedWidget(config)`

`openWidget(message?)`

`closeWidget()`

`toggleWidget()`

`isWidgetOpen()` / `isWidgetReady()`

`showBubbles(messages, duration?)`

`showForm(form, options?)`

`identify(identity)` / `clearIdentity()`

`getVisitorId()`

`triggerEvent(eventName, data?)`

Error Handling

TypeScript

Next Steps