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
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
curl https://katexs.com/api/public/chat/7b0f6c2e-6a51-4a59-9a1b-0e9c4d2f1a77 \
-H "Origin: https://www.example.com"{
"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),endto close the conversation, oridleto 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
sessionevent, if you can't rely on cookies. - identityobject
name(≤100),email,phone(E.164, for example+15125550123) andtextConsent(boolean). Self-reported, never used as proof of identity.
The whole request body may be at most 20,000 bytes.
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.
| type | Fields | Meaning |
|---|---|---|
session | sessionId, visitorToken | Always first. Keep sessionId to continue the conversation. |
delta | text | The next piece of the reply. Append in order. |
tool | name, status | The agent used a tool. Optional to display. |
done | ended | The reply is complete. If ended is true, the conversation was closed by an end phrase. |
error | message | The reply failed. Show the message. The credit is refunded. |
Non-streaming responses
Some outcomes return plain JSON instead of a stream:
| Status | Body | Meaning |
|---|---|---|
| 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
| Scope | Limit |
|---|---|
| Per visitor | 20 messages per minute |
| Per agent (all visitors) | 200 messages per minute |
| Per IP address | 60 messages per minute |
Last updated November 2026 · Found a problem? Email support@katexs.com
