Live Chat API Reference

Complete API documentation for Live Chat system endpoints.

Authentication

Widget Endpoints

Widget endpoints use widget token authentication:

Authorization: Bearer <widget_token>

Dashboard Endpoints

Dashboard endpoints use JWT token authentication:

Authorization: Bearer <jwt_token>

Base URL

https://api.yourdomain.com/api

Widget Endpoints

Send Chat Message

POST /api/widgets/:widgetId/chat

Sends a chat message from the widget and receives AI response.

Parameters:

• widgetId - Tenant ID (from URL)

Request Body:

{
  "sessionId": "session_abc123",
  "message": "Hello, I need help with pricing",
  "assistantId": "asst-123",
  "conversationId": "conv-456"
}

Response: 200 OK

{
  "success": true,
  "conversationId": "conv-456",
  "message": "I'd be happy to help with pricing!",
  "metadata": {
    "model": "gpt-4o-mini",
    "tokens": 150
  }
}

Error Responses:

• 400 - Missing sessionId or message, no assistant configured
• 401 - Invalid widget token
• 404 - Widget not found
• 429 - Usage limit exceeded
• 500 - Server error

Track Widget Event

POST /api/widgets/:widgetId/track

Tracks widget events for analytics.

Parameters:

• widgetId - Tenant ID (from URL)

Request Body:

{
  "sessionId": "session_abc123",
  "event": "widget_opened",
  "timestamp": "2024-01-15T10:00:00Z",
  "metadata": {
    "source": "landing_page"
  }
}

Response: 200 OK

{
  "success": true
}

Start Voice Call

POST /api/widgets/:widgetId/voice/start

Initiates a voice call from the widget.

Parameters:

• widgetId - Tenant ID (from URL)

Request Body:

{
  "sessionId": "session_abc123",
  "assistantId": "asst-123"
}

Response: 200 OK

{
  "success": true,
  "conversationId": "conv-456",
  "assistantId": "asst-123",
  "phoneNumber": "+14165559999"
}

Get Widget Config

GET /api/widgets/:widgetId/config

Retrieves public widget configuration.

Parameters:

• widgetId - Tenant ID (from URL)

Response: 200 OK

{
  "success": true,
  "config": {
    "name": "Your Company",
    "assistantId": "asst-123",
    "widget": {
      "primaryColor": "#3B82F6",
      "position": "bottom-right"
    },
    "branding": {
      "logo": "https://..."
    }
  }
}

WebSocket Endpoints

Note on /ws/chat

The current widget uses HTTP endpoints (especially POST /api/widgets/:widgetId/chat) for chat messaging. If you see /ws/chat referenced elsewhere, treat it as reserved/legacy rather than required for the widget.

Tenant Updates WebSocket

wss://api.yourdomain.com/api/ws/tenant

Authenticated WebSocket for dashboard real-time updates.

Connection:

const ws = new WebSocket('wss://api.yourdomain.com/api/ws/tenant');

Auth Message (required within 5 seconds):

{
  "type": "auth",
  "token": "jwt-token"
}

Event Messages:

{
  "type": "conversation:new",
  "data": {
    "id": "conv-123",
    "channel": "chat",
    "contact_data": {...}
  }
}

Event Types:

• conversation:new - New conversation created
• conversation:updated - Conversation updated
• conversation:qualified - Conversation qualified
• message:new - New message added
• campaign:progress - Campaign progress update

Error Codes

Client Errors (4xx)

• 400 Bad Request - Invalid request data
• 401 Unauthorized - Missing or invalid authentication
• 404 Not Found - Resource not found
• 429 Too Many Requests - Usage limit exceeded

Server Errors (5xx)

• 500 Internal Server Error - Server error

Rate Limiting

• Widget chat messages: Standard rate limits
• WebSocket connections: No rate limits
• Event tracking: No rate limits

Security

Widget Token

• Tenant-specific
• Should be kept secure
• Rotate periodically
• Never expose in client-side code if possible

WebSocket Security

• Chat WebSocket: Widget token authentication
• Tenant WebSocket: JWT token authentication
• HTTPS/WSS required in production
• Connection timeout: 5 seconds for authentication

Related Documentation

• Widget Configuration - Widget setup
• WebSocket Integration - WebSocket details
• Troubleshooting - Error resolution