AI Chat¶

List User Conversations¶

Endpoint: GET /chats

Description: List all chat session titles for a user with pagination. Only session info (title, created_at) is returned.

Query Parameters: - page (integer): Page number (default: 1, min: 1) - per_page (integer): Conversations per page (default: 20, min: 1, max: 100)

Response: 200 OK

{
    "message": "User conversation tiles retrieved successfully",
    "data": {
        "conversations": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "user_id": "user_uuid",
                "title": "My First Chat",
                "created_at": "2025-11-18T21:30:45.123456"
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 20,
            "total_count": 1,
            "total_pages": 1,
            "next": null,
            "prev": null
        }
    }
}

Create New Chat Session¶

Endpoint: POST /chats

Description: Create a new chat session for a user. The title is automatically generated when the user sends the first message in the session.

Response: 201 Created

{
    "message": "Chat session created successfully",
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "user_id": "user_uuid",
        "title": null,
        "created_at": "2025-11-18T21:30:45.123456"
    }
}

Update Chat Title¶

Endpoint: PATCH /chats/{conversation_id}/title

Description: Updates the title of a specific chat conversation.

Request Body:

{
    "title": "My New Chat Title"
}

Response: 200 OK

{
    "message": "Chat session title updated successfully.",
    "data": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "user_id": "user_uuid",
        "title": "My New Chat Title",
        "created_at": "2025-11-18T21:30:45.123456"
    }
}

Get Conversation Messages¶

Endpoint: GET /chats/{convo_id}

Description: Get a conversation (chat session) by ID with all its messages (paginated).

Path Parameters: - convo_id (UUID): UUID of the conversation.

Query Parameters: - page (integer): Page number for pagination (default: 1, min: 1) - per_page (integer): Messages per page (default: 20, min: 1, max: 100)

Response: 200 OK

{
    "message": "Conversation retrieved successfully",
    "data": {
        "conversation": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "user_id": "user_uuid",
            "title": "My First Chat",
            "created_at": "2025-11-18T21:30:45.123456"
        },
        "messages": [
            {
                "id": "message_uuid_1",
                "sender": "user",
                "message": "Hello, Nora!",
                "created_at": "2025-11-18T21:30:45.123456"
            },
            {
                "id": "message_uuid_2",
                "sender": "ai",
                "message": "Hello! How can I assist you today?",
                "created_at": "2025-11-18T21:30:46.789012"
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 20,
            "total_count": 2,
            "total_pages": 1,
            "next": null,
            "prev": null
        }
    }
}

Delete Chat Conversation¶

Endpoint: DELETE /chats/{conversation_id}

Description: Deletes a specific chat conversation.

Path Parameters: - conversation_id (UUID): The ID of the conversation to delete.

Response: 200 OK

{
    "message": "Conversation deleted",
    "success": true
}

Send Message to AI (Streaming)¶

Endpoint: POST /chats/{session_id}/message

Description: Send a message to AI and stream the response via Server-Sent Events (SSE).

Path Parameters: - session_id (UUID): UUID of the chat session.

Request Body:

{
    "message": "What should I expect in my first trimester?",
    "personality": "mother_figure"
}

Response (Server-Sent Events):

SSE Event Types: - start: Initial event with message_id and title (title only present for first message). - chunk: AI response content chunks. - done: Stream completion with AI message_id and optional disclaimer. - error: Error occurred during streaming.

Example start event:

data: {"type": "start", "message_id": "ai_message_uuid", "title": "Pregnancy Questions"}

Example chunk event:

data: {"type": "chunk", "content": "During"}

Example done event (with disclaimer):

data: {"type": "done", "message_id": "ai_message_uuid", "disclaimer": {"primary_category": "pregnancy", "detected_categories": ["pregnancy"], "message": "This information is for educational purposes only..."}}

Real-time Voice Chat (WebSocket)¶

Endpoint: WS /chats/ws/voice/{chat_session_id}?token=<JWT_TOKEN>

Description: Real-time voice chat WebSocket for sending and receiving voice messages. chat_session_id: Can be an existing chat session UUID or any string (a new session will be created if not found). token: JWT access token from login (required, passed as query parameter).

Authentication: Requires a valid JWT access token in the query parameters (?token=<JWT_TOKEN>).

Client-to-Server Messages (JSON):

start_talking: Signals the start of user speaking.
```
{"type": "start_talking"}
```

audio_chunk: Base64 encoded audio data.

{"type": "audio_chunk", "data": "base64_encoded_audio"}

stop_talking: Signals the end of user speaking.
```
{"type": "stop_talking"}
```

ping: Client heartbeat.

{"type": "ping", "timestamp": "current_timestamp"}

Server-to-Client Messages (JSON):

status: General status updates.

{"type": "status", "message": "Listening... Speak now"}

partial_transcript: Partial transcription of user's audio.
```
{"type": "partial_transcript", "text": "What is"}
```

final_transcript: Final transcription of user's audio.

{"type": "final_transcript", "text": "What is the weather like today?"}

ai_response: AI's text response.

{"type": "ai_response", "text": "The weather is sunny.", "is_complete": true, "disclaimer": { ... }}

error: Error message.

{"type": "error", "message": "An error occurred"}

pong: Response to client ping.

{"type": "pong", "timestamp": "received_timestamp"}

title: Generated conversation title (if first message).

{"type": "title", "text": "New Conversation Topic"}