Developer Guides

This section covers everything you need to programmatically integrate Ansa into your applications. Whether you’re building a custom chat experience, syncing data with external systems, or personalizing conversations based on user identity.

Choose Your Integration

JavaScript SDK

Server-side and client-side SDK for Node.js, browsers, and TypeScript. Full API access with streaming support.

Widget API

Control the chat widget programmatically — open, close, send messages, and listen to events.

Forms & Triggers

Trigger forms programmatically and handle submissions with custom callbacks.

User Identity

Pass user context to personalize conversations and pre-fill forms with known data.

Custom Events

Track user actions and trigger automations based on custom events.

Webhooks

Receive real-time notifications when conversations happen or forms are submitted.

Quick Start

Option 1: Embed Script (Recommended)

The simplest way to add Ansa to your site. Add this script before the closing </body> tag:

<script src="https://cdn.ansa.so/embed.js?agentId=YOUR_AGENT_ID"></script>

The ansa object is automatically available on window for programmatic control:

// Open the chat widget
ansa.open();

// Open with a pre-filled message
ansa.open("I need help with my order");

// Close the widget
ansa.close();

// Identify the current user
ansa.identify({
  userId: "user_123",
  userMetadata: {
    name: "Jane Smith",
    email: "jane@example.com",
    plan: "pro"
  }
});

The widget loads asynchronously. To ensure the widget is ready before calling methods:

// Option 1: onReady callback (recommended)
window.ansa?.onReady(() => {
  ansa.identify({ userId: "user_123" });
  ansa.open("Welcome back!");
});

// Option 2: Event listener
window.addEventListener('ansa:ready', () => {
  ansa.identify({ userId: "user_123" });
});

// Option 3: Polling helper
function waitForAnsa(callback) {
  if (window.ansa?.isReady?.()) {
    callback();
  } else {
    setTimeout(() => waitForAnsa(callback), 100);
  }
}

waitForAnsa(() => {
  ansa.open();
});

Use onReady when you need to run code immediately after the widget initializes. The callback fires immediately if the widget is already ready.

Option 2: JavaScript SDK

For server-side integrations or custom chat interfaces, install the SDK:

npm install @ansa-so/sdk

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

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

// Send a message and get a response
const response = await ansa.chat("agent_id", {
  message: "What are your business hours?",
  conversationId: "conv_123", // optional, for multi-turn
});

console.log(response.message);

API Overview

The ansa object exposes these methods when using the embed script:

Method	Description
`ansa.open(message?)`	Open the chat widget, optionally with a pre-filled message
`ansa.close()`	Close the chat widget
`ansa.toggle()`	Toggle the widget open/closed state
`ansa.isOpen()`	Returns `true` if the widget is currently open
`ansa.isReady()`	Returns `true` if the widget has finished initializing
`ansa.onReady(callback)`	Execute callback when widget is ready (fires immediately if already ready)
`ansa.identify(identity)`	Set user identity and metadata
`ansa.resetUser()`	Clear user identity
`ansa.showForm(form, options)`	Display a form in the widget
`ansa.showBubbles(messages, duration?)`	Show notification bubbles
`ansa.hideBubbles()`	Hide notification bubbles
`ansa.trigger(eventName, data?)`	Fire a custom event for triggers
`ansa.getVisitorId()`	Get the anonymous visitor ID

SDK Methods

The AnsaClient provides full API access:

Method	Description
`chat(agentId, options)`	Send a message and receive a response
`streamChat(agentId, options, callbacks)`	Stream responses token-by-token
`getAgent(agentId)`	Retrieve agent configuration
`listAgents()`	List all agents in your organization
`getConversation(id)`	Get conversation history
`listConversations(agentId)`	List conversations for an agent

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your Site     │     │   Ansa Widget   │     │   Ansa API      │
│                 │     │   (iframe)      │     │                 │
│  ┌───────────┐  │     │                 │     │  ┌───────────┐  │
│  │ ansa.open │──┼────▶│   Chat UI       │────▶│  │  /chat    │  │
│  │ ansa.id.. │  │     │                 │     │  │  /agents  │  │
│  └───────────┘  │     │                 │◀────│  │  /tools   │  │
│                 │     │                 │     │  └───────────┘  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │   Your Server   │
                                                │   (webhooks)    │
                                                └─────────────────┘

The widget runs in an iframe for security isolation. Your page communicates with the widget via postMessage, and the widget communicates with the Ansa API. Webhooks notify your server of events in real-time.

Getting Started

User Guides

Use Cases