API Reference

REST API documentation with endpoints for assistants, chats, knowledge base, tools, and webhooks

Overview

Happ provides a REST API for programmatic access to the platform. Use the API to manage assistants, send messages, control AI mode, manage phone numbers, and integrate Happ into your existing workflows.

Interactive API Docs

Full interactive API documentation is available at:

api.happ.tools/reference

The API reference is powered by Scalar and includes all endpoints, request/response schemas, and examples. You can test API calls directly from the documentation.

Base URL

Environment	URL
Production	`https://api.happ.tools`

Authentication

All API requests require an Access Token. Generate one in your account settings at my.happ.tools.

Include the token in the X-Access-Token header:

X-Access-Token: happ_your_token_here

Key Endpoints

Assistants

# List assistants
GET /api/assistants
X-Access-Token: happ_your_token_here

# Create an assistant
POST /api/assistants
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "name": "Support Bot",
  "promptText": "You are a helpful support assistant...",
  "firstMessage": "Hello! How can I help?",
  "llmProvider": "openai",
  "llmModel": "gpt-4o",
  "language": "en"
}

# Update an assistant
PATCH /api/assistants/{assistantId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "name": "Updated Name"
}

Chats

# List chats
GET /api/chats?page=1&take=20
X-Access-Token: happ_your_token_here

# Create a chat
POST /api/chats
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "your-assistant-uuid"
}

# Send a message
POST /api/chats/{chatId}/messages
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "content": "Hello, let me help you with that!"
}

# List messages
GET /api/chats/{chatId}/messages?page=1&take=20
X-Access-Token: happ_your_token_here

# Toggle AI control
PATCH /api/chats/{chatId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "isUnderAiControl": true
}

Knowledge Base

# List knowledge entries
GET /api/assistant-knowledge?assistantId={assistantId}
X-Access-Token: happ_your_token_here

# Create knowledge entry (text)
POST /api/assistant-knowledge
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "your-assistant-uuid",
  "type": "text",
  "name": "FAQ",
  "resourceContent": "Your text content here..."
}

# Delete knowledge entry
DELETE /api/assistant-knowledge/{knowledgeId}
X-Access-Token: happ_your_token_here

Phones

# List phones
GET /api/phones
X-Access-Token: happ_your_token_here

# Add a phone
POST /api/phones
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "phoneNumber": "+380501234567",
  "sipLogin": "your-sip-login",
  "password": "your-sip-password",
  "telephonyUrl": "sip.provider.com",
  "codec": "alaw"
}

# Link phone to assistant
PATCH /api/phones/{phoneId}
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "your-assistant-uuid"
}

Tools

# List tools for an assistant
GET /api/assistant-tools?assistantId={assistantId}
X-Access-Token: happ_your_token_here

# Create a tool
POST /api/assistant-tools
X-Access-Token: happ_your_token_here
Content-Type: application/json

{
  "assistantId": "your-assistant-uuid",
  "name": "check_availability",
  "description": "Check available time slots",
  "type": "webhook_action",
  "apiCallUrl": "https://your-server.com/api/availability",
  "webhookSecret": "your-secret",
  "params": [
    {
      "name": "date",
      "type": "string",
      "description": "Date to check (YYYY-MM-DD)",
      "isRequired": true
    }
  ]
}

WebSocket (Real-time)

Connect to the WebSocket endpoint for real-time updates:

WebSocket URL: wss://api.happ.tools/ws

The WebSocket uses Socket.IO protocol. After connecting:

Authenticate with your token
Join your company room for company-wide events
Receive events: MESSAGE_CREATED, CHAT_MODE_CHANGED, CHAT_CREATED

See Chats > Real-Time Updates for details.

Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": { ... }
}

Paginated responses:

{
  "success": true,
  "data": [...],
  "totalCount": 42,
  "page": 1
}

Error responses:

{
  "success": false,
  "error": {
    "message": "Description of what went wrong",
    "code": "ERROR_CODE"
  }
}

Rate Limits

API requests are subject to rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests response. Wait and retry with exponential backoff.

Full Reference

For complete endpoint documentation with all parameters, schemas, and examples:

api.happ.tools/reference

On this page