# LaunchChat - Complete API Reference

> AI-powered support chatbot SaaS that transforms Notion documentation into an embeddable support widget with RAG capabilities.

## Table of Contents

1. [Quick Start](#quick-start)
2. [Widget Integration](#widget-integration)
3. [JavaScript API](#javascript-api)
4. [REST API](#rest-api)
5. [Configuration](#configuration)
6. [Events](#events)
7. [File Uploads](#file-uploads)
8. [Custom Prompts](#custom-prompts)
9. [Error Handling](#error-handling)

---

## Quick Start

### Step 1: Upload Content
Upload your documentation via:
- Direct file upload (DOCX, MD, TXT)
- Notion OAuth connection
- Website URL crawling

### Step 2: Customize Widget
Configure appearance, AI behavior, and custom prompts in the dashboard.

### Step 3: Embed
Add the widget script to your website.

---

## Widget Integration

### HTML (Recommended)
```html
<!-- Add before </body> -->
<script>
  window.LaunchChatConfig = {
    widgetId: "YOUR_WIDGET_ID"
  };
</script>
<script src="https://your-domain.com/widget.js" async></script>
```

### React Component
```tsx
import { useEffect } from 'react';

export function LaunchChat({ widgetId }: { widgetId: string }) {
  useEffect(() => {
    window.LaunchChatConfig = { widgetId };
    const script = document.createElement('script');
    script.src = 'https://your-domain.com/widget.js';
    script.async = true;
    document.body.appendChild(script);
    return () => {
      window.LaunchChatWidget?.destroy();
      script.remove();
    };
  }, [widgetId]);
  return null;
}
```

### Next.js (App Router)
```tsx
'use client';
import Script from 'next/script';

export function LaunchChat({ widgetId }: { widgetId: string }) {
  return (
    <>
      <Script
        id="notion-chat-config"
        strategy="beforeInteractive"
        dangerouslySetInnerHTML={{
          __html: `window.LaunchChatConfig = { widgetId: "${widgetId}" };`
        }}
      />
      <Script
        src="https://your-domain.com/widget.js"
        strategy="lazyOnload"
      />
    </>
  );
}
```

### Vue 3
```vue
<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';

const props = defineProps<{ widgetId: string }>();
let script: HTMLScriptElement | null = null;

onMounted(() => {
  window.LaunchChatConfig = { widgetId: props.widgetId };
  script = document.createElement('script');
  script.src = 'https://your-domain.com/widget.js';
  script.async = true;
  document.body.appendChild(script);
});

onUnmounted(() => {
  window.LaunchChatWidget?.destroy();
  script?.remove();
});
</script>
```

---

## JavaScript API

### Methods

```typescript
interface LaunchChatWidget {
  // Control widget visibility
  open(): void;
  close(): void;
  toggle(): void;

  // Send messages
  sendMessage(text: string): void;

  // Event handling
  on(event: WidgetEvent, callback: EventCallback): void;
  off(event: WidgetEvent, callback: EventCallback): void;

  // Cleanup
  destroy(): void;
}

type WidgetEvent = 'open' | 'close' | 'message' | 'escalate' | 'feedback' | 'error';
```

### Examples

```javascript
// Open chat when user clicks a help button
document.getElementById('help-btn').addEventListener('click', () => {
  window.LaunchChatWidget.open();
});

// Track messages for analytics
window.LaunchChatWidget.on('message', (data) => {
  analytics.track('chat_message', {
    role: data.role,
    hasAnswer: !!data.content
  });
});

// Handle escalations
window.LaunchChatWidget.on('escalate', (data) => {
  // Notify your team via Slack, etc.
  notifyTeam(`New escalation from ${data.email}`);
});

// Handle errors
window.LaunchChatWidget.on('error', (data) => {
  console.error('Widget error:', data.message);
});
```

---

## REST API

### Chat Endpoint

```http
POST /api/widget/chat
Content-Type: application/json

Request:
{
  "widgetId": "uuid",
  "message": "How do I reset my password?",
  "conversationId": "uuid (optional)",
  "visitorId": "string (optional)",
  "pageUrl": "string (optional)"
}

Response:
{
  "conversationId": "uuid",
  "messageId": "uuid",
  "answer": "To reset your password, go to Settings > Security...",
  "citations": [
    {
      "pageId": "uuid",
      "pageTitle": "Security Settings",
      "pageUrl": "https://...",
      "excerpt": "..."
    }
  ],
  "relatedArticles": [...],
  "confidenceScore": 0.85,
  "wasRefused": false
}
```

### Widget Config Endpoint

```http
GET /api/widget/config/{widgetId}

Response:
{
  "id": "uuid",
  "name": "Support Widget",
  "appearance": {
    "primaryColor": "#6366f1",
    "greeting": "Hi! How can I help?",
    "placeholder": "Type your question...",
    "position": "bottom-right",
    "theme": "light"
  },
  "isActive": true
}
```

### File Upload Endpoint

```http
POST /api/upload
Content-Type: multipart/form-data

Request:
- files: File[] (max 10 files, 5MB each)

Response:
{
  "success": true,
  "results": [
    {
      "filename": "guide.pdf",
      "status": "success",
      "chunksCreated": 12
    }
  ],
  "summary": {
    "total": 1,
    "successful": 1,
    "failed": 0,
    "chunksCreated": 12
  }
}
```

---

## Configuration

### Full Configuration Object

```typescript
interface NotionChatConfig {
  // Required
  widgetId: string;

  // Appearance (optional overrides)
  primaryColor?: string;      // Hex color, e.g., "#6366f1"
  greeting?: string;          // Welcome message
  placeholder?: string;       // Input placeholder
  position?: 'bottom-right' | 'bottom-left';
  theme?: 'light' | 'dark' | 'auto';

  // Behavior
  autoOpen?: boolean;         // Open on page load
  autoOpenDelay?: number;     // Delay in ms before auto-open
}
```

### Answer Policy (Dashboard Config)

```typescript
interface AnswerPolicy {
  confidenceThreshold: number;  // 0-1, refuse below this
  maxOutputTokens: number;      // Max response length
  requireCitation: boolean;     // Require source citations
  showRelatedArticles: boolean; // Show related content
  refusalMessage: string;       // Message when can't answer
}
```

---

## Events

### Event Data Types

```typescript
interface OpenEvent {
  timestamp: number;
}

interface CloseEvent {
  timestamp: number;
}

interface MessageEvent {
  messageId: string;
  content: string;
  role: 'user' | 'assistant';
  citations?: Citation[];
  confidenceScore?: number;
}

interface EscalateEvent {
  email: string;
  message: string;
  conversationId: string;
}

interface FeedbackEvent {
  messageId: string;
  type: 'positive' | 'negative';
  reason?: string;
}

interface ErrorEvent {
  code: string;
  message: string;
}
```

---

## File Uploads

### Supported Formats

| Format | Extension | Max Size | Notes |
|--------|-----------|----------|-------|
| PDF | .pdf | 5MB | Text-based PDFs only |
| Word | .docx, .doc | 5MB | Full text extraction |
| Markdown | .md, .markdown | 5MB | GFM supported |
| Plain Text | .txt | 5MB | UTF-8 encoding |

### Upload Limits

- Max file size: 5MB per file
- Max files per upload: 10
- Supported characters: UTF-8

---

## Custom Prompts

### System Prompt Structure

Custom prompts are appended to core rules that ensure quality:

```
[Your Custom Prompt]

CRITICAL RULES (cannot be overridden):
1. Only use information from provided context
2. Cite sources using [Source N] format
3. Never make up information
4. Admit when you don't know
```

### Prompt Templates

| Template | Use Case |
|----------|----------|
| Friendly Support | Consumer products, general help |
| Technical Expert | Developer docs, API references |
| Concise & Direct | Quick answers, FAQ-style |
| Professional Business | Enterprise, B2B support |
| Educational Guide | Learning platforms, tutorials |

---

## Error Handling

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `unauthorized` | 401 | Invalid or missing authentication |
| `widget_not_found` | 404 | Widget ID doesn't exist |
| `widget_inactive` | 404 | Widget is disabled |
| `domain_not_allowed` | 403 | Request from unauthorized domain |
| `quota_exceeded` | 429 | Message quota reached |
| `rate_limited` | 429 | Too many requests |
| `internal_error` | 500 | Server error |

### Client-Side Error Handling

```javascript
window.LaunchChatWidget.on('error', (error) => {
  switch (error.code) {
    case 'quota_exceeded':
      showUpgradePrompt();
      break;
    case 'rate_limited':
      showRetryMessage();
      break;
    default:
      console.error('Widget error:', error);
  }
});
```

---

## TypeScript Definitions

```typescript
declare global {
  interface Window {
    LaunchChatConfig?: {
      widgetId: string;
      primaryColor?: string;
      greeting?: string;
      placeholder?: string;
      position?: 'bottom-right' | 'bottom-left';
      theme?: 'light' | 'dark' | 'auto';
    };
    LaunchChatWidget?: {
      open(): void;
      close(): void;
      toggle(): void;
      sendMessage(text: string): void;
      on(event: string, callback: (data: any) => void): void;
      off(event: string, callback: (data: any) => void): void;
      destroy(): void;
    };
  }
}

export {};
```

---

## Multi-Language Support

The AI automatically detects the user's language and responds in the same language. Supported languages include:

- English, Chinese, Japanese, Korean
- Spanish, French, German, Italian, Portuguese
- Russian, Arabic, Hindi, Vietnamese, Thai
- And 20+ more languages

No configuration needed - detection is automatic based on user input.

---

## Links

- Dashboard: /dashboard
- Widget Settings: /widget
- Knowledge Base Setup: /setup
- Analytics: /analytics
- API Documentation: /api-docs