Chat Sessions
Chat sessions are conversations between a visitor and an AI Representative. Each session tracks the full message history, supports starring and renaming, and can be archived or deleted when no longer needed.
Authentication required
All chat endpoints require a valid JWT or API key.
Create a session
/api/v1/chat/sessionsCreate a new chat session.
A session acts as a container for messages. Create one when a visitor starts a new conversation with an AI Representative.
List sessions
/api/v1/chat/sessionsList all chat sessions for the authenticated user.
Returns sessions ordered by last activity (most recent first). Use this to build a conversation sidebar or session picker.
Get a session with messages
/api/v1/chat/sessions/{session_id}Retrieve a session including its full message history.
The response includes the session metadata and an ordered array of all messages in the conversation.
Update a session
/api/v1/chat/sessions/{session_id}Rename or star/unstar a session.
Archive a session
/api/v1/chat/sessions/{session_id}/archiveArchive a session. Archived sessions are hidden from the default list but not deleted.
Archiving is a soft removal. The session and its messages are preserved and can be restored later.
Delete a session
/api/v1/chat/sessions/{session_id}Permanently delete a session and all its messages.
Deleting a session removes all messages permanently. This cannot be undone. Consider archiving instead if you may need the conversation later.
Bulk delete sessions
/api/v1/chat/sessions/bulk-deleteDelete multiple sessions in a single request.
Session lifecycle
Create -> Active -> Archive (soft) -> Delete (permanent)
\-> Delete (permanent)
Star important sessions so they are easy to find later. Starred sessions always appear at the top of the session list.