Widget API

When you embed the Ansa widget using the script tag, a ansa object is automatically exposed on the window object. This API lets you programmatically control the widget — open/close the chat, show forms, identify users, and trigger automations.

Basic Setup

Add the embed script to your page:

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

The ansa object is available immediately after the script loads:

// Check if widget is ready
if (ansa.isReady()) {
  ansa.open();
}

API Reference

`ansa.open(message?)`

Opens the chat widget. Optionally pre-fill the input with a message.

// Just open the chat
ansa.open();

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

Parameters:

Parameter	Type	Description
`message`	`string?`	Optional message to pre-fill in the input

`ansa.close()`

Closes the chat widget.

ansa.close();

`ansa.toggle()`

Toggles the widget between open and closed states.

// Toggle on button click
document.getElementById("chat-btn").addEventListener("click", () => {
  ansa.toggle();
});

`ansa.isOpen()`

Returns whether the widget is currently open.

if (ansa.isOpen()) {
  console.log("Chat is visible");
} else {
  console.log("Chat is hidden");
}

Returns: boolean

`ansa.isReady()`

Returns whether the widget has finished initializing.

// Wait for widget to be ready
function waitForAnsa(callback) {
  if (window.ansa?.isReady()) {
    callback();
  } else {
    setTimeout(() => waitForAnsa(callback), 100);
  }
}

waitForAnsa(() => {
  ansa.identify({ userId: "user_123" });
});

Returns: boolean

`ansa.showBubbles(messages, duration?)`

Shows notification bubble(s) near the widget button. Great for proactive engagement.

// Single message
ansa.showBubbles("👋 Need help?");

// Multiple messages (appear with staggered timing)
ansa.showBubbles(["Welcome!", "Ask me anything about our products"]);

// Auto-hide after 10 seconds
ansa.showBubbles("Limited time offer!", 10);

Parameters:

Parameter	Type	Description
`messages`	`string \| string[]`	Message(s) to display
`duration`	`number?`	Seconds before auto-hide (optional)

`ansa.hideBubbles()`

Hides any visible notification bubbles.

ansa.hideBubbles();

`ansa.showForm(form, options?)`

Displays a form in the widget. Can reference a server-side form by name or provide a client-side schema.

// Server-side form (defined in dashboard)
ansa.showForm("contact_form");

// Client-side form with custom schema
ansa.showForm({
  fields: [
    { name: "name", label: "Your Name", type: "text" },
    { name: "email", label: "Email", type: "email" },
    {
      name: "interest",
      label: "Interest",
      type: "select",
      options: [
        { label: "Sales", value: "sales" },
        { label: "Support", value: "support" }
      ]
    }
  ],
  submitButtonText: "Get Started"
}, {
  onSubmit: (data) => {
    console.log("Form data:", data);
    // { name: "Jane", email: "jane@example.com", interest: "sales" }
  },
  onCancel: () => {
    console.log("User cancelled");
  },
  sendToAgent: true // Send form data as chat message
});

Parameters:

Parameter	Type	Description
`form`	`string \| FormSchema`	Tool name (server) or form schema (client)
`options.onSubmit`	`function?`	Called with form data on submit
`options.onCancel`	`function?`	Called when form is cancelled
`options.sendToAgent`	`boolean?`	Also send data to agent as message

See Triggering Forms for complete form schema reference.

`ansa.trigger(eventName, data?)`

Fires a custom event that can trigger automations.

// Simple event
ansa.trigger("pricing_viewed");

// Event with data
ansa.trigger("product_viewed", {
  productId: "prod_123",
  category: "electronics",
  price: 299.99
});

Parameters:

Parameter	Type	Description
`eventName`	`string`	Name of the custom event
`data`	`object?`	Optional event payload

See Custom Events for setting up event-based triggers.

`ansa.identify(identity)`

Sets the current user’s identity. This personalizes the chat experience and pre-fills forms.

ansa.identify({
  userId: "user_abc123",
  userMetadata: {
    name: "Jane Smith",
    email: "jane@example.com",
    plan: "enterprise",
    company: "Acme Inc",
    signupDate: "2024-01-15"
  }
});

Parameters:

Property	Type	Description
`userId`	`string?`	Your internal user ID
`userMetadata`	`object?`	Additional user properties

See Identity for personalization use cases.

`ansa.resetUser()`

Clears the current user identity (e.g., on logout).

// When user logs out
function logout() {
  ansa.resetUser();
  // ... rest of logout logic
}

`ansa.getVisitorId()`

Returns the anonymous visitor ID (persisted in localStorage).

const visitorId = ansa.getVisitorId();
console.log(visitorId); // "v_1703347200000_abc123def"

Returns: string — Unique visitor identifier

`ansa.registerFormSchema(schemas)`

Registers client-side form schema providers. Forms are generated dynamically based on context.

ansa.registerFormSchema({
  "quote_form": async (args, user) => {
    // Fetch options from your API
    const products = await fetch("/api/products").then(r => r.json());

    return {
      fields: [
        { name: "email", label: "Email", type: "email", defaultValue: user.userMetadata?.email },
        {
          name: "product",
          label: "Product",
          type: "select",
          options: products.map(p => ({ label: p.name, value: p.id }))
        },
        { name: "quantity", label: "Quantity", type: "number" }
      ],
      submitButtonText: "Get Quote"
    };
  }
});

Parameters:

Parameter	Type	Description
`schemas`	`object`	Map of form name → schema provider function

The schema provider receives:

args: Arguments passed from the agent tool call
user: User context ({ visitorId, userId?, userMetadata?, conversationId? })

`ansa.hasFormSchema(name)`

Checks if a form schema provider is registered.

if (ansa.hasFormSchema("quote_form")) {
  console.log("Quote form is available");
}

Returns: boolean

`ansa.registerFormHandler(name, handler)` Legacy

Registers a form submission handler for server-side forms.

ansa.registerFormHandler("order_lookup", {
  onInit: ({ agentId }) => {
    console.log("Handler initialized for agent:", agentId);
  },
  onSubmit: async (context) => {
    const { formData, conversationId } = context;

    // Look up order in your system
    const order = await fetch(`/api/orders/${formData.orderId}`).then(r => r.json());

    return {
      success: true,
      message: `Order ${order.id} is ${order.status}`,
      data: order
    };
  }
});

`ansa.unregisterFormHandler(name)` Legacy

Removes a registered form handler.

ansa.unregisterFormHandler("order_lookup");

`ansa.hasFormHandler(name)` Legacy

Checks if a form handler is registered.

if (ansa.hasFormHandler("order_lookup")) {
  console.log("Order lookup is available");
}

Configuration

Script Parameters

Configure the widget via URL parameters:

<script src="https://cdn.ansa.so/embed.js?agentId=xxx&theme=dark&primaryColor=%233b82f6"></script>

Parameter	Type	Description
`agentId`	`string`	Your agent ID (required)
`theme`	`"light" \| "dark"`	Color theme
`primaryColor`	`string`	Primary accent color (URL-encoded hex)
`chatBubbleColor`	`string`	Chat bubble button color
`displayName`	`string`	Agent display name
`profilePicture`	`string`	Agent avatar URL
`initialMessage`	`string`	First message from agent
`messagePlaceholder`	`string`	Input placeholder text
`suggestedMessages`	`string`	Comma-separated suggestions
`welcomeBubbles`	`string`	Comma-separated bubble messages

Window Config

Alternatively, set config before loading the script:

<script>
  window.__ansa_config = {
    agentId: "agent_abc123",
    theme: "dark",
    primaryColor: "#3b82f6",
    displayName: "Sales Bot",
    suggestedMessages: ["Pricing info", "Book a demo", "Talk to sales"],
    welcomeBubbles: ["👋 Hi there!", "How can I help you today?"]
  };
</script>
<script src="https://cdn.ansa.so/embed.js"></script>

Common Patterns

Open Chat on Button Click

<button onclick="ansa.open()">Chat with us</button>

Open Chat with Context

// On product page
document.getElementById("product-help").addEventListener("click", () => {
  const productName = document.querySelector("h1").textContent;
  ansa.open(`I have a question about ${productName}`);
});

async function onLoginSuccess(user) {
  ansa.identify({
    userId: user.id,
    userMetadata: {
      name: user.name,
      email: user.email,
      plan: user.subscription.plan
    }
  });
}

Proactive Engagement

// Show help bubble after 30 seconds on pricing page
if (window.location.pathname === "/pricing") {
  setTimeout(() => {
    ansa.showBubbles("Have questions about our plans? I can help!", 15);
  }, 30000);
}

Custom Chat Trigger

// Open chat when user shows exit intent
document.addEventListener("mouseleave", (e) => {
  if (e.clientY < 0 && !ansa.isOpen()) {
    ansa.showBubbles("Wait! Can I help you find what you're looking for?");
  }
});

React Integration

import { useEffect } from "react";

declare global {
  interface Window {
    ansa?: {
      open: (message?: string) => void;
      close: () => void;
      identify: (identity: { userId?: string; userMetadata?: Record<string, unknown> }) => void;
      isReady: () => boolean;
    };
  }
}

export function useAnsa() {
  const open = (message?: string) => window.ansa?.open(message);
  const close = () => window.ansa?.close();
  const identify = (userId: string, metadata?: Record<string, unknown>) => {
    window.ansa?.identify({ userId, userMetadata: metadata });
  };

  return { open, close, identify };
}

// Usage
function ChatButton() {
  const { open } = useAnsa();
  return <button onClick={() => open()}>Chat</button>;
}

Getting Started

User Guides

Use Cases

Developer Guides

Tools & Forms

Integrations

API Reference

Support

Basic Setup

API Reference

`ansa.open(message?)`

`ansa.close()`

`ansa.toggle()`

`ansa.isOpen()`

`ansa.isReady()`

`ansa.showBubbles(messages, duration?)`

`ansa.hideBubbles()`

`ansa.showForm(form, options?)`

`ansa.trigger(eventName, data?)`

`ansa.identify(identity)`

`ansa.resetUser()`

`ansa.getVisitorId()`

`ansa.registerFormSchema(schemas)`

`ansa.hasFormSchema(name)`

`ansa.registerFormHandler(name, handler)` Legacy

`ansa.unregisterFormHandler(name)` Legacy

`ansa.hasFormHandler(name)` Legacy

Configuration

Script Parameters

Window Config

Common Patterns

Open Chat on Button Click

Open Chat with Context

Proactive Engagement

Custom Chat Trigger

React Integration

Next Steps

Triggering Forms

Identity

​Basic Setup

​API Reference

​ansa.open(message?)

​ansa.close()

​ansa.toggle()

​ansa.isOpen()

​ansa.isReady()

​ansa.showBubbles(messages, duration?)

​ansa.hideBubbles()

​ansa.showForm(form, options?)

​ansa.trigger(eventName, data?)

​ansa.identify(identity)

​ansa.resetUser()

​ansa.getVisitorId()

​ansa.registerFormSchema(schemas)

​ansa.hasFormSchema(name)

​ansa.registerFormHandler(name, handler) Legacy

​ansa.unregisterFormHandler(name) Legacy

​ansa.hasFormHandler(name) Legacy

​Configuration

​Script Parameters

​Window Config

​Common Patterns

​Open Chat on Button Click

​Open Chat with Context

​Identify User on Login

​Proactive Engagement

​Custom Chat Trigger

​React Integration

​Next Steps

Triggering Forms

Identity

Basic Setup

API Reference

`ansa.open(message?)`

`ansa.close()`

`ansa.toggle()`

`ansa.isOpen()`

`ansa.isReady()`

`ansa.showBubbles(messages, duration?)`

`ansa.hideBubbles()`

`ansa.showForm(form, options?)`

`ansa.trigger(eventName, data?)`

`ansa.identify(identity)`

`ansa.resetUser()`

`ansa.getVisitorId()`

`ansa.registerFormSchema(schemas)`

`ansa.hasFormSchema(name)`

`ansa.registerFormHandler(name, handler)` Legacy

`ansa.unregisterFormHandler(name)` Legacy

`ansa.hasFormHandler(name)` Legacy

Configuration

Script Parameters

Window Config

Common Patterns

Open Chat on Button Click

Open Chat with Context

Identify User on Login

Proactive Engagement

Custom Chat Trigger

React Integration

Next Steps