Endpoints

GET /api/v1/notification/

Get notifications for the authenticated merchant.

Authentication: Required (Merchant JWT token)

Query Parameters: - status (optional): Filter by notification status (requested | answered) - notification_types (optional): Filter by notification types (array of NotificationType values)

Response: 200 OK

[
    {
        "id": 123,
        "notification_type": "user_question_request",
        "status": "requested",
        "created_at": "2025-10-28T10:30:00Z",
        "updated_at": "2025-10-28T10:30:00Z",
        "conversation_id": 456,
        "context": {
            "question": "What are your business hours?",
            "document_id": 789,
            "lead_phone": "+1234567890"
        },
        "requested_fields": ["question"],
        "answered_fields": ["answer"]
    }
]

Error Responses: - 401 Unauthorized: Invalid or missing JWT token

Usage: - Merchant dashboard can display open notifications - Filter by status to show only unanswered notifications - Filter by type to separate questions from support tickets

Implementation: Calls get_notifications service function

POST /api/v1/notification/{notification_id}/answer

Answer a notification (alternative to using AnswerNotificationTool in chat).

Authentication: Required (Merchant JWT token)

Path Parameters: - notification_id: ID of the notification to answer

Request Body:

{
    "answer": "We are open Mon-Fri 9am-5pm EST"
}

Or for support requests:

{
    "agent_response_to_customer": "Please send your order number and we'll process the refund",
    "resolution_notes": "Customer eligible for full refund, item damaged"
}

Response: 200 OK

{
    "message": "Notification answered successfully"
}

Error Responses: - 401 Unauthorized: Invalid or missing JWT token - 404 Not Found: Notification doesn't exist or doesn't belong to merchant - 500 Internal Server Error: Validation error or processing failure

Validation: - Notification must belong to authenticated merchant - Notification must exist and be answerable - Answer context must include all answered_fields - Answer must match notification's JSON schema

Implementation: Calls answer_notification service function

Note: Most merchant admins answer via AnswerNotificationTool in their WhatsApp conversation. This endpoint provides an alternative method (e.g., for dashboard UI).

DELETE /api/v1/notification/{notification_id}

Delete a notification.

Authentication: Required (Merchant JWT token)

Path Parameters: - notification_id: ID of the notification to delete

Response: 200 OK

{
    "message": "Notification deleted successfully"
}

Error Responses: - 401 Unauthorized: Invalid or missing JWT token - 404 Not Found: Notification doesn't exist or doesn't belong to merchant

Use Cases: - Merchant wants to dismiss a notification without answering - Notification sent by mistake - Customer already resolved issue through another channel

Implementation: Direct SQLAlchemy delete operation

POST /api/v1/notification/request

Create a new notification request (alternative to triggering via Voyager).

Authentication: Required (Merchant JWT token)

Request Body:

{
    "notification_type": "user_question_request",
    "conversation_id": 456,
    "context": {
        "question": "Do you ship internationally?"
    }
}

Or for support requests:

{
    "notification_type": "user_support_request",
    "conversation_id": 789,
    "context": {
        "support_request_reason": "Product damaged on arrival, need refund"
    }
}

Response: 200 OK

{
    "message": "Notification requested successfully"
}

Error Responses: - 401 Unauthorized: Invalid or missing JWT token - 500 Internal Server Error: Missing required fields or processing failure

Validation: - All requested_fields must be present in context - Conversation must exist - Notification type must be valid

Implementation: Calls request_notification service function

Note: Most notifications are triggered automatically via Voyager tools (RequestNotificationTool). This endpoint allows manual creation from dashboard or external integrations.

Authentication

All notification endpoints require merchant authentication via JWT token.

Token Verification: - Uses verify_access_token dependency from Auth Service - Returns MerchantTokenPayload with merchant_id - Validates token signature and expiration

Authorization: - Notifications are scoped to merchant_id - Queries always filter by merchant ownership via conversation relationship - Prevents cross-merchant data access

Common Request Patterns

Get Unanswered Notifications

GET /api/v1/notification/?status=requested
Authorization: Bearer <jwt_token>

Get Support Tickets Only

GET /api/v1/notification/?notification_types=user_support_request
Authorization: Bearer <jwt_token>

Answer Question from Dashboard

POST /api/v1/notification/123/answer
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
    "answer": "Yes, we ship worldwide with 5-10 day delivery"
}

Manually Create Support Ticket

POST /api/v1/notification/request
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
    "notification_type": "user_support_request",
    "conversation_id": 789,
    "context": {
        "support_request_reason": "Customer wants to change delivery address"
    }
}

Rate Limiting

Notification endpoints are subject to standard API rate limits: - No specific notification limits currently implemented - Campaign sending respects WhatsApp daily messaging limits - See Campaign Service for details

Error Handling Best Practices

Client-Side Handling

For GET /: - Handle 401 by redirecting to login - Empty array [] indicates no notifications (not an error)

For POST /{id}/answer: - 404 may indicate notification already deleted or doesn't belong to merchant - 500 with validation error should show error message to user for correction - Success should refresh notification list to remove answered notification

For POST /request: - Validate context includes required fields before calling - 500 errors indicate missing fields or invalid configuration

Server-Side Error Messages

All 500 errors include descriptive detail: - "Answer validation failed against JSON schema: <details>" - "Missing admin response content in context (expected field: answer)" - "This notification has already been answered and cannot be answered again." - "<field> is required"

Use these to guide users on fixing their requests.