On this page
This document provides the technical specification for integrating the Flowk chat backend into custom frontends. This API is used by the standard web widget and supports authenticated users, guest sessions, real-time streaming, and human-agent takeover.
Base URL: https://api-flowk.kemonai.com
Authentication
All requests must include your API Key in the X-Flowk-Key header. Generate and manage your keys in the API Channel Settings.
GET /{agentId}/chat
X-Flowk-Key: fl_live_your_key_here1Initiate or Resume a Session
/{agentId}/sessionCall this endpoint to obtain a session_id. If a customer_id is provided and an active session exists for that customer, it will be resumed.
{
"customer_id": "unique-id-123",
"customer_name": "Jane Doe",
"customer_email": "[email protected]",
"customer_avatar_url": "https://example.com/avatar.png",
"metadata": {
"source": "mobile_app",
"version": "2.4.0"
}
}2Send a Message
/{agentId}/chatSends a message from the customer to the AI agent. This endpoint is asynchronous and returns immediately.
{
"session_id": "sid_01j7p...",
"message": "I need help with my subscription."
}3Real-time Event Stream (SSE)
/{agentId}/sessions/{sid}/eventsServer-Sent Events Protocol
The event stream delivers messages as they happen. If `chunks` is not null, the message is streaming (typewriter effect).
{
"id": "ev_01j7q...",
"source": "ai_agent",
"message": "Hello! I can certainly help with that.",
"chunks": null
}4Resolve (End) Conversation
/{agentId}/sessions/{sid}/resolveMarks the conversation as resolved from the customer's side. This officially closes the session and stops further processing by the AI agent.
{
"status": "ok",
"message": "Conversation marked as resolved."
}Expert Implementation Tips
Session Resumption
Always store session_id in local storage to allow users to refresh without losing history.
Typewriter Effect
Monitor the chunks field. Turn finalizes once an event ends with null.