API Reference

Complete reference for the Widget API and REST endpoints.

Widget API

The global window.LaunchChatWidget object provides methods to control the widget programmatically.

Methods

open()

Opens the chat window programmatically.

window.LaunchChatWidget.open();

close()

Closes the chat window.

window.LaunchChatWidget.close();

destroy()

Removes the widget from the page completely. Useful for SPAs when navigating away.

window.LaunchChatWidget.destroy();

init(config)

Re-initializes the widget with a new configuration.

window.LaunchChatWidget.init({ widgetId: "new-widget-id" });

on(event, callback)

Subscribe to widget events.

window.LaunchChatWidget.on('message', (data) => {
  console.log('New message:', data);
});

off(event, callback)

Unsubscribe from widget events.

Events

Event	Payload	Description
`open`	`{ timestamp }`	Chat window opened
`close`	`{ timestamp }`	Chat window closed
`message`	`{ content, role }`	Message sent or received
`escalate`	`{ email, message }`	User requested human support
`feedback`	`{ messageId, type }`	User gave feedback (positive/negative)

REST API

POST /api/widget/chat

Send a message and receive an AI-generated response.

Request Body

{
  "widgetId": "string",      // Required
  "message": "string",       // Required - user's question
  "conversationId": "string", // Optional - for context
  "visitorId": "string",     // Optional - track visitor
  "pageUrl": "string"        // Optional - current page
}

Response

{
  "conversationId": "uuid",
  "messageId": "uuid",
  "answer": "string",
  "citations": [
    {
      "pageId": "string",
      "pageTitle": "string",
      "pageUrl": "string",
      "excerpt": "string"
    }
  ],
  "relatedArticles": [...],
  "confidenceScore": 0.85,
  "wasRefused": false
}

Error Codes

Code	Status	Description
`400`	Bad Request	Missing required fields
`403`	Forbidden	Domain not in allowlist
`404`	Not Found	Widget not found or inactive
`429`	Rate Limited	Message quota exceeded
`500`	Server Error	Internal processing error

TypeScript Types

Copy these types into your project for full type safety:

interface LaunchChatConfig {
  widgetId: string;
  primaryColor?: string;
  greeting?: string;
  placeholder?: string;
  position?: 'bottom-right' | 'bottom-left';
  theme?: 'light' | 'dark' | 'auto';
}

interface WidgetAPI {
  open(): void;
  close(): void;
  destroy(): void;
  init(config: { widgetId: string }): Promise<void>;
  on<E extends keyof WidgetEvents>(
    event: E,
    callback: (data: WidgetEvents[E]) => void
  ): void;
  off<E extends keyof WidgetEvents>(
    event: E,
    callback: (data: WidgetEvents[E]) => void
  ): void;
}

interface WidgetEvents {
  open: { timestamp: number };
  close: { timestamp: number };
  message: { content: string; role: 'user' | 'assistant' };
  escalate: { email: string; message: string };
  feedback: { messageId: string; type: 'positive' | 'negative' };
}

declare global {
  interface Window {
    LaunchChatConfig?: LaunchChatConfig;
    LaunchChatWidget?: WidgetAPI;
  }
}