Katexs
Chat streaming API

Chat

Chat streaming API

The public endpoint the widget uses. Build your own chat interface on an allowed website, with replies streamed as server-sent events.

Endpoint

GET/api/public/chat/{publicId}
POST/api/public/chat/{publicId}

Base URL: https://katexs.com. publicId is the agent's public deployment id from the embed code.

Warning

This endpoint is for browsers on your allowed origins. Requests without an allowed Origin header are refused with 403, so it can't be called server to server. Send requests with credentials: "include" so the visitor cookie is kept. A server-side chat API is part of the REST API preview.

Load the widget configuration

Request
curl https://katexs.com/api/public/chat/7b0f6c2e-6a51-4a59-9a1b-0e9c4d2f1a77 \
  -H "Origin: https://www.example.com"
200 OK
{
  "widget": {
    "brandName": "Riverside Dental",
    "logoUrl": "",
    "color": "#34D399",
    "position": "bottom-right",
    "theme": "dark",
    "greeting": "Hi! How can I help you today?",
    "quickReplies": ["Book a cleaning", "Opening hours"],
    "prechat": { "name": true, "email": false, "phone": false }
  },
  "connected": true,
  "message": null,
  "idleTimeoutSeconds": 600
}

When connected is false, show message to the visitor and don't send messages.

Send a message

actionenum
message (default), end to close the conversation, or idle to close it if it has been idle past the timeout.
messagestringrequired for message
The visitor's text, up to 4000 characters.
messageIduuid
Your id for this message. Reusing it makes retries safe: a duplicate is refused instead of charged twice.
sessionIduuid
The conversation to continue. Omit to start a new one.
visitorTokenstring
The token from a previous session event, if you can't rely on cookies.
identityobject
name (≤100), email, phone (E.164, for example +15125550123) and textConsent (boolean). Self-reported, never used as proof of identity.

The whole request body may be at most 20,000 bytes.

Browser
const res = await fetch("https://katexs.com/api/public/chat/" + publicId, {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Do you take Delta Dental?", sessionId, messageId: crypto.randomUUID() }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const frames = buffer.split("\n\n");
  buffer = frames.pop() ?? "";
  for (const frame of frames) {
    if (!frame.startsWith("data: ")) continue;
    const event = JSON.parse(frame.slice(6));
    if (event.type === "session") sessionId = event.sessionId;
    if (event.type === "delta") appendToBubble(event.text);
    if (event.type === "error") showError(event.message);
    if (event.type === "done" && event.ended) closeChat();
  }
}

Stream events

The response is text/event-stream. Each event is one data: line with a JSON object.

typeFieldsMeaning
sessionsessionId, visitorTokenAlways first. Keep sessionId to continue the conversation.
deltatextThe next piece of the reply. Append in order.
toolname, statusThe agent used a tool. Optional to display.
doneendedThe reply is complete. If ended is true, the conversation was closed by an end phrase.
errormessageThe reply failed. Show the message. The credit is refunded.

Non-streaming responses

Some outcomes return plain JSON instead of a stream:

StatusBodyMeaning
200{ "offline": true, "message": "..." }The agent isn't live, or a reply is already in progress for this session.
200{ "ended": true } / { "ended": false }Result of an end or idle action.
400{ "error": "Please check your message and contact details." }The body failed validation.
401{ "error": "Please reopen the chat to start a new session." }The visitor token is invalid or expired.
403{ "error": "This website is not authorized for this assistant." }The origin isn't allowed.
403{ "error": "This chat session is unavailable." }The session doesn't belong to this visitor.
404{ "error": "..." }Unknown public id, or the agent isn't deployed yet.
409{ "error": "This conversation has ended. Reopen chat to start again." }Send without sessionId to start a new one.
413{ "error": "Message is too long." }Over 20,000 bytes.
429{ "error": "A few too many messages. Please wait a minute and try again." }Rate limited. Honor the Retry-After header (60 seconds).
503{ "error": "Chat is temporarily offline. Please try again later." }Temporary platform problem. Retry with backoff.

Rate limits

ScopeLimit
Per visitor20 messages per minute
Per agent (all visitors)200 messages per minute
Per IP address60 messages per minute
Chat streaming request The widget loads its configuration, posts a message, the runtime checks origin, visitor token, rate limits and credits, then streams the model reply back as server-sent events. Visitor browserwidget.js Katexs chat runtime/api/public/chat/{publicId} ModelDirect LLM or flow engine 1 Origin on allow-list 2 Signed visitor token 3 Rate limits 4 Reserve credits GET load widget config { widget, connected } POST { message, sessionId } prompt + memory + knowledge streamed tokens data: {"type":"session", …} data: {"type":"delta","text":"…"} data: {"type":"done"} On completionCommit usage and transcript, or refund
One chat message from the website widget, from checks to the streamed reply.

Last updated November 2026 · Found a problem? Email support@katexs.com