API Documentation for Frontend Integration

This document provides a comprehensive guide to the MNotify-Copianto API, including authentication, endpoints, request/response formats, and WebSocket integration. The API provides functionalities for chat interactions, content management, vector database training, and conversation history.

Base URL

Production: https://your-production-url.com
Development: http://localhost:8000

Authentication

All API requests require authentication using an API key.

API Key Authentication

Header-based: Include the API key in the X-API-Key header:

X-API-Key: a1022ce5188258d89c5157db1a821db8b74d13aaeb0c0463e427ffff9d87d165

Query Parameter: Include the API key as a query parameter:

/api/endpoint?api_key=a1022ce5188258d89c5157db1a821db8b74d13aaeb0c0463e427ffff9d87d165

WebSocket URL Path: Include the API key in the WebSocket URL:

ws://example.com/ws/chat/a1022ce5188258d89c5157db1a821db8b74d13aaeb0c0463e427ffff9d87d165/

Authentication Errors

401 Unauthorized: Invalid or expired API key
403 Forbidden: Insufficient permissions

WebSocket Chat Integration

Connection

URL: ws://{base_url}/ws/chat/{api_key}/
Protocol: WebSocket (ws:// or wss://)

Connection Lifecycle

Connect: Open a WebSocket connection to the endpoint

Handshake:

On successful connection, the server sends:

{
  "type": "connection_established",
  "message": "Connected to MNotify Bot"
}

Server assigns chat group and client IDs:

{
  "type": "chat_group_assigned",
  "chat_group_id": "uuid-string",
  "client_id": "uuid-string"
}

Sending Messages:

{
  "type": "message",
  "message": "Your question here",
  "client_id": "optional-client-id",
  "chat_group_id": "optional-group-id"
}

With Category Filtering:

{
  "type": "message",
  "message": "What policies do you know?",
  "category_ids": ["Policy", "Regulation"],  // Optional: filter by category names
  "client_id": "optional-client-id",
  "chat_group_id": "optional-group-id"
}

Receiving Streaming Responses:

Token messages during streaming:

{
  "type": "token",
  "token": "partial text chunk",
  "is_streaming": true
}

Streaming completion notification:

{
  "type": "streaming_complete",
  "partial_message": "full message so far",
  "is_streaming": false
}

Final message with references:

{
  "type": "message",
  "message": "Complete response text",
  "is_bot": true,
  "conversation_id": "uuid-string",
  "chat_group_id": "group-id",
  "client_id": "client-id",
  "timestamp": "2025-06-07T10:22:23.016Z",
  "references": [
    {
      "title": "Document Title",
      "source": "Source URL or description",
      "category": "Category Name",
      "reference_number": 1
    }
  ],
  "has_reference": true,
  "reference_numbers": [1, 2],
  "complete": true
}

Confirmation of message delivery:

{
  "type": "message_delivered",
  "conversation_id": "uuid-string",
  "timestamp": "2025-06-07T10:22:25.016Z"
}

Handling Connection Issues:
- Implement automatic reconnection logic
- Store client_id and chat_group_id for session continuity
- Handle code 1006 (abnormal closure) with exponential backoff

WebSocket Message Types

Type	Description	Direction
`connection_established`	Initial connection confirmation	Server → Client
`chat_group_assigned`	Assigns conversation grouping	Server → Client
`message`	User question or bot response	Bidirectional
`token`	Streaming partial response	Server → Client
`streaming_complete`	Indicates streaming is complete	Server → Client
`typing`	Bot typing indicator	Server → Client
`ping`	Connection heartbeat	Server → Client
`message_received`	Confirms receipt of user message	Server → Client
`error`	Error information	Server → Client
`history_request`	Request for conversation history	Client → Server
`chat_history`	Conversation history data	Server → Client
`message_delivered`	Confirms final message delivery	Server → Client

RESTful API Endpoints

Category Management

List Categories

GET /api/chat/categories/

Response: List of categories

[
  {
    "id": 1,
    "name": "Tax Policy",
    "description": "Tax-related policies and regulations",
    "created_at": "2025-06-07T10:22:23.016Z",
    "updated_at": "2025-06-07T10:22:23.016Z"
  }
]

Create Category

POST /api/chat/categories/

Request Body:

{
  "name": "New Category",
  "description": "Description of the category"  // Optional
}

Response: Created category object

Update Category

PUT/PATCH /api/chat/categories/{id}/

Request Body:

{
  "name": "Updated Category Name",
  "description": "Updated description"
}

Response: Updated category object

Delete Category

DELETE /api/chat/categories/{id}/

Response: 204 No Content

File Management

List Files

GET /api/chat/files/

Query Parameters:

category: Filter by category ID
trained: Filter by training status (true/false)

Response:

[
  {
    "id": 1,
    "name": "File name",
    "file": "/media/path/to/file.pdf",
    "is_trained": false,
    "show_as_reference": true,
    "category": 1,
    "category_name": "Category Name",
    "created_at": "2025-06-07T10:22:23.016Z",
    "updated_at": "2025-06-07T10:22:23.016Z"
  }
]

Upload File

POST /api/chat/files/

Content-Type: multipart/form-data

Form Fields:

file: File data (required)
name: File name (optional, defaults to filename)
category: Category ID (optional)
show_as_reference: Boolean (optional, default: true)

Response: Created file object

Batch Upload Files

POST /api/chat/files/batch/

Content-Type: multipart/form-data

Form Fields:

files: Multiple file data (required)
category: Category ID (optional)
show_as_reference: Boolean (optional, default: true)

Response: Array of created file objects

Delete File

DELETE /api/chat/files/{id}/

Response: 204 No Content

Text Content Management

List Texts

GET /api/chat/texts/

Query Parameters:

category: Filter by category ID
trained: Filter by training status (true/false)

Response: List of text objects

Create Text

POST /api/chat/texts/

Request Body:

{
  "text": "Text content",
  "name": "Text title",
  "category": 1,
  "show_as_reference": true
}

Response: Created text object

Batch Create Texts

POST /api/chat/texts/batch/

Request Body:

{
  "texts": ["Text content 1", "Text content 2"],
  "category": 1,
  "show_as_reference": true
}

Response: Array of created text objects

Delete Text

DELETE /api/chat/texts/{id}/

Response: 204 No Content

Website Management

List Websites

GET /api/chat/websites/

Query Parameters:

category: Filter by category ID
trained: Filter by training status (true/false)
ready: Filter by ready status (true/false)

Response: List of website objects

Add Website

POST /api/chat/websites/

Request Body:

{
  "url": "https://example.com",
  "category": 1,
  "show_as_reference": true,
  "follow_links": false,
  "is_js_heavy": false,
  "wait_for_page_load": 15,
  "wait_for_id": "",
  "wait_for_class": "",
  "ignore_urls": ""
}

Response: Created website object

Batch Add Websites

POST /api/chat/websites/batch/

Request Body:

{
  "urls": ["https://example1.com", "https://example2.com"],
  "category": 1,
  "show_as_reference": true,
  "follow_links": false,
  "is_js_heavy": false,
  "wait_for_page_load": 15,
  "wait_for_id": "",
  "wait_for_class": "",
  "ignore_urls": ""
}

Response: Array of created website objects

Delete Website

DELETE /api/chat/websites/{id}/

Response: 204 No Content

Training and Bot Management

Train Bot

GET /api/chat/train/

Response:

{
  "task_id": "celery-task-id",
  "status": "Training started"
}

Get Bot Status

GET /api/chat/status/

Response:

{
  "id": 1,
  "index_name": "MN20250604123456",
  "is_trained": true,
  "new_data_added": false,
  "last_trained_at": "2025-06-07T10:22:23.016Z",
  "file_count": 10,
  "text_count": 5,
  "website_count": 3,
  "untrained_count": 0,
  "untrained_details": {
    "files": [],
    "texts": [],
    "websites": [],
    "not_ready_websites": [],
    "count": {
      "files": 0,
      "texts": 0,
      "websites": 0,
      "not_ready_websites": 0,
      "total": 0
    }
  },
  "created_at": "2025-06-07T10:22:23.016Z",
  "updated_at": "2025-06-07T10:22:23.016Z"
}

Reset Bot

POST /api/chat/reset/

Request Body:

{
  "delete_weaviate_index": false
}

Response:

{
  "message": "Bot training status reset successfully. All data sources marked for retraining."
}

Check Task Status

GET /api/chat/task-status/{task_id}/

Response:

{
  "task_id": "task-id",
  "status": "PENDING|IN_PROGRESS|COMPLETED|FAILED",
  "result": {},
  "task_type": "TRAINING",
  "is_active": true
}

Conversation Management

Get Conversation History

GET /api/chat/conversations/

Query Parameters:

client_id: Filter by client ID (optional)
chat_group_id: Filter by chat group ID (optional)

Response:

{
  "conversations": [
    {
      "id": 1,
      "conversation_id": "uuid-string",
      "client_id": "client-id",
      "user_input": "Question text",
      "chatbot_response": "Answer text",
      "created_at": "2025-06-07T10:22:23.016Z",
      "full_response": {},
      "similar_docs": [],
      "like_or_dislike": null
    }
  ]
}

Delete Conversation

DELETE /api/chat/conversations/delete/{id}/

Response: 204 No Content

Bot Settings

Get Bot Settings

GET /api/chat/settings/

Note: This endpoint now only returns user-configurable fields.

Response:

{
  "id": 1,
  "name": "Ghana Policy Assistant",
  "extra_prompt": "Always cite sources with reference numbers",
  "created_at": "2025-06-07T10:22:23.016Z",
  "updated_at": "2025-06-07T10:22:23.016Z"
}

Update Bot Settings

PUT /api/chat/settings/

Note: Only name and extra_prompt fields can be updated.

Request Body:

{
  "name": "Ghana Policy Bot",
  "extra_prompt": "Focus on Ghana-specific regulations and always mention the source"
}

Response: Updated settings object (only exposed fields)

Reset Bot Settings

POST /api/chat/settings/

Response: Default settings object

Content Extraction

Extract Content

POST /api/chat/extract/content/

Request Body:

{
  "batch_size": 10,
  "force": false
}

Response:

{
  "message": "Content extraction started for 5 files",
  "task_id": "uuid-string",
  "total_files": 5,
  "batch_size": 10,
  "status": "PENDING"
}

Get Extraction Status

GET /api/chat/extract/status/

GET /api/chat/extract/status/?task_id=<task_id>

Response (without task_id):

{
  "total_files": 10,
  "extracted_files": 8,
  "ready_files": 8,
  "pending_files": 2,
  "extraction_progress": 80.0,
  "active_tasks": [
    {
      "task_id": "task-id",
      "status": "IN_PROGRESS",
      "created_at": "2025-06-07T10:22:23.016Z",
      "result": {}
    }
  ],
  "active_task_count": 1
}

Import Functions

Import Folder

POST /api/chat/import/folder/

Content-Type: multipart/form-data

Form Fields:

folder_zip: ZIP file with folder structure
category (optional): Category ID
show_as_reference (optional): Boolean, default true

Response:

{
  "message": "Folder import started",
  "task_id": "uuid-string",
  "status": "PENDING"
}

Get Import Status

GET /api/chat/import/status/

GET /api/chat/import/status/?task_id=<task_id>

Response: Similar to extraction status

Category-Based Question Filtering

The API supports filtering bot responses based on specific content categories. This allows you to restrict the bot's knowledge base to specific topics or domains.

How Category Filtering Works

No categories specified: Bot searches all available categories
Categories specified: Bot only searches within those specific categories
Invalid categories: System validates and warns about invalid category names

WebSocket Category Filtering

Include category_ids array with category names in your message:

{
  "type": "message",
  "message": "Tell me about tax policies",
  "category_ids": ["Tax", "Finance"]  // Filter by category names
}

Category Validation

If invalid categories are provided, you'll receive a warning:

{
  "type": "warning",
  "message": "Invalid category IDs: ['NonExistent']. Using valid categories only."
}

Client History Management

New endpoints for managing conversation history when WebSocket clients disconnect and need to restore their state.

Get Client Chat History

GET /api/chat/client-history/

Query Parameters:

client_id (required): The client ID from WebSocket connection
chat_group_id (optional): Filter by specific chat group
date_from (optional): Filter from date (YYYY-MM-DD)
date_to (optional): Filter to date (YYYY-MM-DD)
limit (optional): Limit results (default: 50, max: 200)

Response:

{
  "client_id": "abc123",
  "total_count": 25,
  "conversations": [
    {
      "id": 1,
      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
      "client_id": "abc123",
      "user_input": "What policies do you know?",
      "chatbot_response": "I can help you with various policies...",
      "created_at": "2025-01-15T10:30:00Z",
      "full_response": {},
      "similar_docs": [],
      "like_or_dislike": null
    }
  ],
  "conversations_by_group": {
    "group456": [/* conversations */]
  },
  "filters_applied": {
    "chat_group_id": null,
    "date_from": null,
    "date_to": null,
    "limit": 50
  }
}

Get Client Chat Groups

GET /api/chat/client-groups/

Query Parameters:

client_id (required): The client ID

Response:

{
  "client_id": "abc123",
  "chat_groups": [
    {
      "chat_group_id": "group456",
      "conversation_count": 15,
      "last_message_at": "2025-01-15T10:30:00Z",
      "first_message_at": "2025-01-14T08:00:00Z"
    }
  ],
  "total_groups": 2
}

Get Specific Conversation

GET /api/chat/conversation/{conversation_id}/

Path Parameters:

conversation_id: UUID of the conversation

Response:

{
  "conversation": {
    "id": 1,
    "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_id": "abc123",
    "user_input": "What policies do you know?",
    "chatbot_response": "I can help you with various policies...",
    "created_at": "2025-01-15T10:30:00Z",
    "full_response": {},
    "similar_docs": [],
    "like_or_dislike": null
  },
  "metadata": {
    "client_id": "abc123",
    "chat_group_id": "group456",
    "created_at": "2025-01-15T10:30:00Z",
    "has_response": true,
    "has_references": true,
    "user_feedback": null,
    "related_conversations": 24
  }
}

Error Handling

All API endpoints follow a consistent error response format:

Common HTTP Status Codes

200 OK: Successful request
201 Created: Resource created successfully
204 No Content: Resource deleted successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Missing or invalid authentication
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server-side error

Error Response Format

{
  "detail": "Error message"
}

{
  "field_name": ["Error message"]
}

Recent API Changes

This section documents recent changes to the API that may require frontend updates.

January 2025 Updates

1. Category-Based Filtering (New Feature)

WebSocket: Added category_ids field to message requests
Behavior: Bot can now filter responses by specific content categories
Validation: Invalid categories return warnings but don't stop processing

2. Client History Endpoints (New)

GET /api/chat/client-history/ - Retrieve conversation history by client_id
GET /api/chat/client-groups/ - List chat groups for a client
GET /api/chat/conversation/{conversation_id}/ - Get specific conversation details

3. Bot Settings API Changes (Breaking)

Restricted Fields: Only name and extra_prompt are now exposed
Removed Fields: model, temperature, prompt, use_default_prompt, max_tokens are no longer accessible via API
Impact: Frontend should only display/edit name and extra_prompt fields

4. Bot Name Customization (Enhancement)

Bot now introduces itself using the configured name from settings
Default changed from "Entrepreneurship Policy Assistant" to configurable name
extra_prompt is automatically integrated into bot behavior

5. Category Name Changes

Categories now use names (strings) instead of numeric IDs in WebSocket messages
Example: category_ids: ["Tax", "Finance"] instead of category_ids: [1, 2]

Migration Guide

For WebSocket Implementations:

// Old way (if you were using categories)
{
  "type": "message",
  "message": "What policies?",
  "category_ids": [1, 2]  // Numeric IDs
}

// New way
{
  "type": "message", 
  "message": "What policies?",
  "category_ids": ["Tax", "Finance"]  // Category names
}

For Session Recovery:

// Use new client history endpoint after reconnection
const response = await fetch(`/api/chat/client-history/?client_id=${clientId}&limit=20`, {
  headers: { 'X-API-Key': apiKey }
});

const { conversations } = await response.json();
// Restore UI with conversation history

For additional support or questions, please contact the backend development team.