#Client Chat API

Status: Available. The /api/widget/* routes work today and are used by the widget itself. They are not packaged as a versioned contract (no version prefix, no OpenAPI): the field set is described from the code as of 12 Oct 2026 (widget v2: header by state, visitor files, cards). Only init sends CORS headers; read Known limitations before you start.

Purpose: build your own chat interface ("headless"): the same calls the widget frame makes, with your own design.

#Contents

1. When to use it
2. Access and general rules
3. How it works
4. Session token
5. POST /api/widget/init
6. POST /api/widget/messages
7. Consent to the terms
8. GET /api/widget/history
9. GET /api/widget/poll
10. GET /api/widget/events (SSE)
11. POST /api/widget/upload
12. Conversation states
13. Card in a message
14. Limits
15. Error summary
16. Example: a chat in plain JavaScript
17. Example: a React component
18. Known limitations
19. Notes
20. Open questions

#When to use it

• You need a chat interface with your own design, or inside your app.
• The widget does not suit you in look or placement.

If the standard window is enough, use the widget. If you need the reply on your own server or in your own messenger, use the server API (Available).

#Access and general rules

The server API conventions (Conventions: problem+json, the code catalog, Idempotency-Key, cursors, operation) do not apply to these routes: client API responses are plain {"error": "…"} objects, not application/problem+json. The same case of an exhausted daily limit is reported by the server API with the field ai_reply: {status: "skipped", reason: "daily_limit"}.

#How it works

  Your interface                                     Cell
      │  POST /init   {channel_id} ───────────────►  name, color, greeting,
      │ ◄─────────────────────────────────────────  form, consent, header (assistant,
      │                                              queue), label, file rules
      │
      │  POST /messages {channel_id, content,       first message: no session yet
      │                  [session_token]} ────────►
      │ ◄── {session_token, response, queued?} ───  save session_token
      │
      │  GET /events?st=<token>  (SSE) ◄──────────  operator replies, typing
      │  or GET /poll?st=<token> every 2.5 s
      │  GET /history?st=<token>  on open           conversation history
      │  POST /upload?st=<token> (multipart)        file → message with an attachment

#Session token

The token is issued in the response to the first message (POST /messages) and refreshed in every response. Save the latest one.

The token is the key to the conversation. Do not write it to logs or to addresses that third parties can see. A token in the query (st) ends up in the logs of your proxies and server.

The conversation ID is not returned in responses: it is needed only inside the token.

#POST /api/widget/init

Status: Available.

Get the channel settings for rendering the interface. The only route with CORS.

#Request

POST /api/widget/init

curl -X POST https://formula-cream.pro/api/widget/init \
  -H 'Content-Type: application/json' \
  -d '{"channel_id":"00000000-0000-4000-8000-000000000000"}'

#Response 200

The tenant sets assistant, queue, powered_by, and files in the dashboard or through the tenant API; details are in Embedding, branding. Paths on the tenant's own site in icon addresses are returned as an absolute address on the cell. The top-level name and avatar_url are kept for older clients: avatar_url equals assistant.avatar_url.

{
  "channel_id": "00000000-0000-4000-8000-000000000000",
  "name": "Formula Cream",
  "greeting": "Hello! How can we help?",
  "color": "#6366f1",
  "avatar_url": null,
  "pre_chat_form": null,
  "locale": "ru",
  "assistant": { "name": "School assistant", "subtitle": "We reply instantly", "avatar_url": null },
  "queue": { "title": "Waiting for an operator", "subtitle": "An operator will join shortly", "icon_url": null },
  "powered_by": { "text": "Powered by Formula AI", "url": null },
  "files": { "visitor_upload": true, "max_mb": 10, "accept": ["image/jpeg", "image/png", "application/pdf"] },
  "consent": {
    "text": "I agree to the terms of the offer",
    "url": "https://formula-cream.pro/offer",
    "version": "3a7bd3e2360a3d29"
  }
}

The greeting is local: you need to display it yourself. It does not come from the history and is not stored as a message.

#Errors

OPTIONS returns 204 with CORS headers.

init does not check whether your domain is allowed for the chat window (frame-ancestors). That applies only to the embedded frame; it does not affect your own interface.

#POST /api/widget/messages

Status: Available.

Send a visitor's message and get the AI reply. A paid operation.

#Request

POST /api/widget/messages, Content-Type: application/json

The server does not read the fields sender_email and sender_phone that the widget frame sends: do not rely on them (limitations).

curl -X POST https://formula-cream.pro/api/widget/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "channel_id": "00000000-0000-4000-8000-000000000000",
    "content": "How much does the course cost?",
    "sender_name": "Anna",
    "page_url": "https://shop.example.com/courses/hydrolat-basics",
    "page_title": "Hydrolat Basics",
    "consent_version": "3a7bd3e2360a3d29"
  }'

#Response 200

{
  "session_token": "w1.eyJjIjoiMDAwMDAwMDAifQ.c2lnbmF0dXJl",
  "response": "The \"Hydrolat Basics\" course costs 9,900 RUB. Would you like to hear what is included?"
}

{
  "session_token": "w1.eyJjIjoiMDAwMDAwMDAifQ.c2lnbmF0dXJl",
  "response": null,
  "queued": true
}

The shape of the response field when there is no AI reply (an empty string or null) is not fixed in the code: handle both. The exact reasons for the absence of a reply are not disclosed in the client API; they are available only in the server API.

#Errors

A retry after 429, 500, or 503 may record the message a second time: this route has no idempotency. If in doubt, read history and resend only if the message is not there.

#What happens on the server

• The visitor's identity is determined only by the session token. Without it, or with an invalid one, it is a new visitor.
• The conversation metadata records the site host, the path (up to 200 characters), page_key, the query (up to 200 characters), and source: "embedded_widget" (details).
• The model receives the address as host and path, without the query.
• Attribution is recorded only for tenants; its failure does not cancel the reply.
• If an operator is handling the conversation, the AI does not reply.
• Daily AI limit: the channel's ai_daily_limit (200 by default, 10,000 at most). After the limit, queued: true.

#Consent to the terms

If the tenant set a consent_text, the server does not accept messages without consent.

Procedure:

1. init returns consent: {text, url, version}. If the key is absent, no consent is required.
2. Show the text and (if present) the url link with a checkbox. Do not send a message until the checkbox is ticked.
3. Pass consent_version = consent.version in every POST /messages. Passing it in the first one is enough: the consent is recorded in the conversation.
4. If the tenant changes the text or the link, the version changes. The server will respond 400 consent_required with the current consent: show it again and retry with the new version.

The version is the first 16 hexadecimal characters of sha256(text + "\n" + url). Do not compute it yourself: take the ready value from init or from the 400 response.

The consent record: kind: "offer", version, accepted_at, text_sha256, url, ip (the visitor's original IP; see the limitation).

{
  "error": "consent_required",
  "consent": {
    "text": "I agree to the terms of the offer",
    "url": "https://formula-cream.pro/offer",
    "version": "3a7bd3e2360a3d29"
  }
}

#GET /api/widget/history

Status: Available.

The conversation history, for restoring the window when the page reloads.

#Request

GET /api/widget/history?st=<session_token>

#Response 200

{
  "messages": [
    { "id": "11111111-1111-4111-8111-111111111111", "sender": "user", "content": "How much does the course cost?", "created_at": "2026-10-11T08:15:30Z" },
    { "id": "22222222-2222-4222-8222-222222222222", "sender": "ai", "content": "The course costs 9,900 RUB.", "created_at": "2026-10-11T08:15:33Z" },
    {
      "id": "44444444-4444-4444-8444-444444444444", "sender": "operator", "content": "Here is the diagram and the course card.",
      "created_at": "2026-10-11T08:17:10Z",
      "operator": { "name": "Anna", "avatar_url": "https://formula-cream.pro/storage/operators/anna.jpg" },
      "attachments": [
        { "name": "scheme.pdf", "type": "application/pdf", "size": 84213, "url": "https://formula-cream.pro/storage/…", "expires_at": "2026-10-11T09:17:10Z" }
      ],
      "cards": [
        {
          "code": "hydrolat-basics", "name": "Hydrolat Basics", "description": "A course for beginners", "image_url": null,
          "price_text": "9,900 RUB", "badge": "Bestseller", "page_url": "/courses/hydrolat-basics",
          "buttons": [ { "label": "Enroll", "url": "https://formula-cream.pro/courses/hydrolat-basics" } ]
        }
      ]
    }
  ],
  "state": "operator",
  "operator": { "name": "Anna", "avatar_url": "https://formula-cream.pro/storage/operators/anna.jpg" }
}

At most 500 messages are returned, in ascending time order. Staff internal notes (is_internal) are not included.

#Errors

#GET /api/widget/poll

Status: Available.

A fallback way to receive new messages when the event stream (SSE) is unavailable. The widget frame polls every 2.5 seconds. Without after, every response contains all the AI and operator messages of the conversation, so keep track of the ids you have shown on the client side, or pass after with the time of the last message.

#Request

GET /api/widget/poll?st=<session_token>[&after=<time>]

#Response 200

{
  "new_messages": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "sender": "operator",
      "content": "Hello! My name is Anna, I'll tell you more.",
      "created_at": "2026-10-11T08:17:02Z",
      "operator": { "name": "Anna", "avatar_url": null }
    }
  ],
  "state": "operator",
  "operator": { "name": "Anna", "avatar_url": null },
  "typing": false,
  "typing_name": ""
}

Errors are the same as for history.

#GET /api/widget/events (SSE)

Status: Available.

A Server-Sent Events stream: operator and AI replies arrive without polling.

#Request

GET /api/widget/events?st=<session_token>, through EventSource.

Response headers: Content-Type: text/event-stream, Cache-Control: no-cache, no-transform, X-Accel-Buffering: no. The first line of the stream is : connected.

#Events

: connected

event: status
data: {"status":"SUBSCRIBED"}

event: message
data: {"id":"33333333-3333-4333-8333-333333333333","sender":"operator","content":"Hello!","created_at":"2026-10-11T08:17:02Z"}

event: heartbeat
data: {"ts":1760170000000}

Properties:

• Access is rechecked every 60 seconds; on a denial, closed arrives.
• The AI reply to your message may, according to the code, arrive twice: in the body of POST /messages (the response field) and as a message event with a database ID (the reply is written to the database, and the stream delivers any message not from the visitor). Not verified on live data. Protect yourself: compare sender and content with recent messages and keep the ids you have shown.
• The visitor's own messages do not appear in the stream.
• EventSource automatic reconnection works; after a drop, read history so you do not lose messages.
• Errors before the stream starts: 401, 404, 500 with the plain-text body Session not available.

#POST /api/widget/upload

Status: Available. The visitor's file is saved to the conversation's private storage and creates a visitor message with an attachment; the operator sees it in "Conversations".

Upload a file on behalf of the visitor. Uploads can be turned off in the channel settings (files.visitor_upload, see init).

#Request

POST /api/widget/upload?st=<session_token>, Content-Type: multipart/form-data

The session token is accepted in the address (st, as the frame sends it) or in the form field session_token. The Content-Length header is required: without it the response is 411. The size is checked before the body is parsed.

Allowed types: JPEG, PNG, GIF, and WebP images; PDF; DOC, DOCX; XLS, XLSX; TXT, CSV, MD. Archives are not accepted. The extension, MIME type, and file signature are checked; dangerous extensions are blocked. The channel returns the current list of MIME types in init (files.accept).

You can upload once the conversation has started: there is an AI or operator reply, or the visitor has written two messages. Otherwise the response is 409 conversation_not_ready.

curl -X POST 'https://formula-cream.pro/api/widget/upload?st=w1.…' \
  -F '[email protected]' \
  -F 'channel_id=00000000-0000-4000-8000-000000000000'

#Response 200

{
  "message_id": "55555555-5555-4555-8555-555555555555",
  "created_at": "2026-10-11T08:20:00Z",
  "attachment": {
    "name": "scheme.pdf",
    "type": "application/pdf",
    "size": 84213,
    "url": "https://formula-cream.pro/storage/…",
    "expires_at": "2026-10-11T09:20:00Z"
  }
}

url is a signed link to a private file; it is valid for about an hour. The file is not public: to get a fresh link, read history. The message is already created; you do not need to send a separate POST /messages with the address. The file is not passed to the AI model.

#Quotas

#Errors

The per-IP rate check runs before the body is parsed.

#Conversation states

Every message, history, and poll carry the conversation state, and SSE reports a change of it with the conversation:update event. The widget changes its header accordingly.

Build your own interface the same way: take the title and subtitle from init while state is ai or queued, and from operator when state is operator.

#Card in a message

Product cards arrive in the cards field of a message (up to 10 in one message). The tenant creates them in the dashboard or through the API, and an operator, the AI seller, or a server call sends them into the conversation.

Display the texts as text, not as HTML. Do not render or follow addresses with other schemes (javascript:, data:).

#Limits

Counters in process memory are not shared between several processes and reset on restart. The client routes have no Retry-After headers or remaining-limit headers: on 429, wait a minute.

#Error summary

The error body is {"error": "<code or text>"}; for events it is text. Branch your logic on the status and on the error string where it is described above; the texts Session not available and Too many requests are not meant to be parsed.

#Example: a chat in plain JavaScript

The working file is examples/custom-chat-vanilla.html, with a configurable API_BASE (see CORS). The main fragments follow.

const API_BASE = 'https://formula-cream.pro';          // your cell
const CHANNEL_ID = '00000000-0000-4000-8000-000000000000';
const TOKEN_KEY = 'my_chat_token';

let token = localStorage.getItem(TOKEN_KEY) || '';
let consentVersion = '';
const shown = new Set();                                // IDs of messages already shown

async function api(path, options) {
  const res = await fetch(API_BASE + path, options);
  let body = null;
  try { body = await res.json(); } catch { /* not JSON */ }
  return { ok: res.ok, status: res.status, body };
}

// 1. Channel settings and consent
async function init() {
  const { ok, body } = await api('/api/widget/init', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ channel_id: CHANNEL_ID })
  });
  if (!ok) throw new Error('Channel unavailable');
  addMessage('ai', body.greeting);                      // we display the greeting ourselves
  if (body.consent) consentVersion = body.consent.version;
  return body;
}

// 2. Sending a message
async function send(text) {
  const payload = {
    channel_id: CHANNEL_ID,
    content: text,
    session_token: token || undefined,
    page_url: location.href,
    page_title: document.title,
    consent_version: consentVersion || undefined
  };
  const { ok, status, body } = await api('/api/widget/messages', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });

  if (status === 400 && body && body.error === 'consent_required') {
    consentVersion = body.consent.version;              // show the consent and retry
    throw new Error('consent_required');
  }
  if (status === 413) throw new Error('Message too long');
  if (status === 429) throw new Error('Too many requests, wait a minute');
  if (!ok) throw new Error('Could not send');

  token = body.session_token;
  localStorage.setItem(TOKEN_KEY, token);
  if (body.queued) addMessage('system', 'Handed to an operator, who will reply later');
  else if (body.response) addMessage('ai', body.response);
}

// 3. Subscribing to operator replies: SSE with a fallback poll
function listen() {
  if (!token) return;
  const es = new EventSource(API_BASE + '/api/widget/events?st=' + encodeURIComponent(token));
  es.addEventListener('message', (e) => {
    const m = JSON.parse(e.data);
    addMessage(m.sender, m.content, m.id);
  });
  es.addEventListener('closed', () => es.close());
  es.onerror = () => { es.close(); setTimeout(poll, 2500); };
}

async function poll() {
  if (!token) return;
  const { ok, body } = await api('/api/widget/poll?st=' + encodeURIComponent(token));
  if (ok) body.new_messages.forEach((m) => addMessage(m.sender, m.content, m.id));
  setTimeout(poll, 2500);
}

// 4. Displaying without duplicates
function addMessage(sender, content, id) {
  if (id) {
    if (shown.has(id)) return;
    shown.add(id);
  }
  // the AI reply from POST and the same reply from SSE: compare sender+content with the last message
  const last = document.querySelector('#log > :last-child');
  if (last && last.dataset.sender === sender && last.textContent === content) return;
  const div = document.createElement('div');
  div.dataset.sender = sender;
  div.textContent = content;                            // not innerHTML: the text is untrusted
  document.querySelector('#log').appendChild(div);
}

Key points:

• Render text with textContent, not innerHTML: replies come from the model and the operator.
• Save the token after every response.
• After a page reload, restore the window from history, then connect the stream.

#Example: a React component

The working file is examples/custom-chat-react.jsx.

import { useEffect, useRef, useState } from 'react';

const API_BASE = 'https://formula-cream.pro';
const CHANNEL_ID = '00000000-0000-4000-8000-000000000000';

export function ChatBox() {
  const [messages, setMessages] = useState([]);
  const [text, setText] = useState('');
  const [busy, setBusy] = useState(false);
  const token = useRef(localStorage.getItem('my_chat_token') || '');
  const consent = useRef('');

  const add = (m) =>
    setMessages((list) => {
      if (m.id && list.some((x) => x.id === m.id)) return list;
      const last = list[list.length - 1];
      if (last && last.sender === m.sender && last.content === m.content) return list;
      return [...list, m];
    });

  useEffect(() => {
    let es;
    (async () => {
      const init = await fetch(`${API_BASE}/api/widget/init`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ channel_id: CHANNEL_ID })
      }).then((r) => r.json());
      if (init.consent) consent.current = init.consent.version;
      add({ sender: 'ai', content: init.greeting });

      if (token.current) {
        es = new EventSource(`${API_BASE}/api/widget/events?st=${encodeURIComponent(token.current)}`);
        es.addEventListener('message', (e) => add(JSON.parse(e.data)));
      }
    })();
    return () => es && es.close();
  }, []);

  async function submit(e) {
    e.preventDefault();
    if (!text.trim() || busy) return;
    setBusy(true);
    add({ sender: 'user', content: text });
    const res = await fetch(`${API_BASE}/api/widget/messages`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        channel_id: CHANNEL_ID,
        content: text,
        session_token: token.current || undefined,
        consent_version: consent.current || undefined
      })
    });
    const body = await res.json().catch(() => ({}));
    setBusy(false);
    if (!res.ok) return add({ sender: 'system', content: `Error ${res.status}` });
    token.current = body.session_token;
    localStorage.setItem('my_chat_token', token.current);
    if (body.response) add({ sender: 'ai', content: body.response });
    setText('');
  }

  return (
    <form onSubmit={submit}>
      <ul>{messages.map((m, i) => <li key={m.id || i}>{m.content}</li>)}</ul>
      <input value={text} onChange={(e) => setText(e.target.value)} maxLength={4000} />
      <button disabled={busy}>Send</button>
    </form>
  );
}

#Known limitations

The wording is neutral: from the code as of 11 Oct 2026.

Additionally, not from the list:

• Possible duplication of the AI reply (the POST /messages body and SSE). Deduplicate.
• No idempotency on POST /messages: a retry after a network failure may create a second message.
• No versioning. The contract may change; for a durable integration from your server, use the server API.

#Notes

• If you build the interface on the cell's domain (for example, your own page inside the cell), CORS is not required.
• For SSE behind your proxy, turn off buffering (proxy_buffering off) and keep X-Accel-Buffering: no.
• Hosting proxies often cut SSE connections after 30 to 60 seconds: rely on the fallback poll.
• File links are signed and live for about an hour: do not store them as permanent addresses, re-read history.
• Changelog: 90-changelog.

#Open questions

• Whether CORS headers will be added to all client routes, or a versioned contract (/api/public/v1/chat/*) will be released: the project describes only the "Client Chat API" section, and there are no dates.
• The shape of the response field when the AI did not reply (null or an empty string), and the reasons for the absence of a reply in the client API, are not fixed in the code. Technical.
• The structure of pre_chat_form (field names, required flags) is described here from the frame's behavior; the exact schema is not published in the project.
• SSE (Realtime) operation on each of the three cells was not verified as part of this documentation.

Templates and examples