Overview The Sessions API allows admin users to view active WhatsApp conversations, retrieve message history, toggle bot automation, and send manual messages to customers.
All endpoints require admin authentication via JWT token.
Endpoints List Active Sessions Fetches all WhatsApp sessions updated within the last 7 days, ordered by most recent activity.
Bearer token from admin login
Response Array of session objects Unique session identifier (UUID)
Customer name or phone number (fallback)
Last message in conversation
Session status: bot, human, or handover
Unread message count (currently always 0)
Example Request curl https://api.example.com/api/sessions \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Example Response [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Juan Pérez" , "phone" : "+573001234567" , "lastMsg" : "¿Tienen el aceite de lavanda disponible?" , "time" : "2026-03-04T10:30:00Z" , "status" : "bot" , "unread" : 0 }, { "id" : "660e8400-e29b-41d4-a716-446655440001" , "phone" : "+573009876543" , "lastMsg" : "Quiero hablar con un humano" , "time" : "2026-03-04T09:15:00Z" , "status" : "handover" , "unread" : 0 } ]
Get Session Messages GET /api/sessions/:id/messages
Retrieves the conversation history for a specific session.
Path Parameters Bearer token from admin login
Response Array of message objects Message sender: user or assistant
Timestamp (currently “Recently”)
Whether AI bot is currently active for this session
Example Request curl https://api.example.com/api/sessions/550e8400-e29b-41d4-a716-446655440000/messages \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Example Response { "messages" : [ { "role" : "user" , "content" : "Hola" , "time" : "Recently" }, { "role" : "assistant" , "content" : "¡Hola! Soy el asistente virtual de KAIU. ¿En qué puedo ayudarte?" , "time" : "Recently" }, { "role" : "user" , "content" : "¿Tienen aceite de lavanda?" , "time" : "Recently" } ], "isBotActive" : true }
Toggle Bot Status PATCH /api/sessions/:id/toggle
Enable or disable the AI bot for a specific session. When disabled, messages will not trigger automated responses.
Path Parameters Bearer token from admin login
Request Body Set to true to enable bot, false to disable
Response Returns the updated session object with new isBotActive status.
Set to "MANUAL_OVERRIDE" when manually disabled, or null when re-enabled
Example Request curl -X PATCH https://api.example.com/api/sessions/550e8400-e29b-41d4-a716-446655440000/toggle \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"isBotActive": false}'
Example Response { "id" : "550e8400-e29b-41d4-a716-446655440000" , "phoneNumber" : "+573001234567" , "isBotActive" : false , "handoverTrigger" : "MANUAL_OVERRIDE" , "updatedAt" : "2026-03-04T11:00:00Z" }
Send Manual Message Send a manual message to a customer via WhatsApp. This endpoint sends the message through the WhatsApp Cloud API and appends it to the session history.
Bearer token from admin login
Request Body Response true if message was sent successfully
Example Request curl -X POST https://api.example.com/api/messages/send \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sessionId": "550e8400-e29b-41d4-a716-446655440000", "content": "Hola Juan, un momento por favor mientras verifico el inventario de lavanda." }'
Example Response Error Response { "error" : "Session not found" }
Upload Product Image Upload a product image to Supabase Storage. Returns a public URL that can be used in product image arrays.
Requires Supabase to be configured with SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY environment variables.
Bearer token from admin login
Request Body Image file (JPEG, PNG, etc.)
Response Public URL of the uploaded image
Example Request curl -X POST https://api.example.com/api/upload \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -F "[email protected] "
Example Response { "url" : "https://example.supabase.co/storage/v1/object/public/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg" }
Error Responses No file uploaded: { "error" : "No file uploaded" }
Supabase not configured: { "error" : "Failed to upload file to Supabase" }
Implementation Notes Session History Storage Message history is stored in the sessionContext.history JSON field of the WhatsAppSession model. Each message has:
role: Either "user" or "assistant"content: Message textimages: Optional array of image URLs (for messages with images)
Real-time Updates When bot status changes or messages are sent, Socket.IO events are emitted to notify connected dashboard clients:
io . emit ( 'session_update' , { id: sessionId , status: 'handover' }); io . to ( `session_ ${ sessionId } ` ). emit ( 'new_message' , { message });
Security All endpoints use the requireAdmin middleware which:
Verifies JWT token from Authorization header
Checks token validity and expiration
Returns 401 Unauthorized if invalid
See Authentication for details on obtaining JWT tokens.
Next Steps