Use the built-in Chat
The platform contains an AI chat bot for shop customers. Which bot answers — and how it is primed — is part of the backend setup: the tenant configures the provider (OpenAI or Claude models, or a simple echo bot for testing), the bot name, a greeting, a primer prompt and a knowledge base. The API abstracts all provider details away: clients talk to two endpoints regardless of the configured provider.
The standard shop frontend's chat widget is built on exactly these endpoints.
Methods
| Method | Purpose | Response Types |
|---|---|---|
| chat1 | send a question (or a command) and receive the bot's answer | ChatControl + ChatResponse |
| chatscript1 | read the transcript of the current (or a given) conversation | ChatResponse |
(/api/chat and /api/chatscript are the untyped legacy predecessors; new clients should use
the versioned methods above.)
Availability and the ChatControl status
Whether chat is available depends on the tenant's UseChat setup (off / admin / on / public)
and on the executor: without a logged-on user, chat only works when the shop allows public
chat. Every chat1 response starts with a
ChatControl object:
| status | meaning |
|---|---|
| -2 | chat (bot) is disabled in this system, or not open for the current (anonymous) user |
| 0 | chat is configured but currently offline |
| 1 | online (control only, no answer included) |
| 2 | OK — a ChatResponse with the answer follows |
Check the status before rendering a chat UI: a client should simply not offer chat when the
first probe returns a status below 1. Unexpected server-side errors are returned as HTTP 410
with the exit code in the X-oekobox-error header.
The chat session
A conversation is a chat session, identified by a sid (a UUID, global parameter
chat_sid). You normally never handle it yourself:
- The
sidis kept in the server-side web session. As long as requests share the web session (see use-api), the conversation continues automatically. - The first question without a session creates a new chat session; the assigned
sidis contained in every ChatResponse. - Sessions that were ended or archived (e.g. by an admin) are transparently replaced by a new one on the next question.
- There is always only one active conversation per user; pass
sid(chat1) /chatid(chatscript1) explicitly only when operating without a shared web session, or as an admin looking into another user's transcript.
Sending questions and commands
Send a question with q:
GET <base>/api/chat1?q=Wann%20kommt%20meine%20Lieferung%3F&oo-rf=json
Alternatively c sends a command instead of a question — one of archive, delete, flag
(flagging marks a conversation for review, e.g. when an answer was wrong).
Reading the answer
A ChatResponse carries the same answer in two forms plus an optional machine-readable part:
speech— plain text, intended for text-to-speech output.display— display-ready HTML; the content matchesspeechbut the formatting depends on the provider.action— a microformat action string the client may interpret, e.g.[g:123]advises the client to show (or link to) item group 123. This is how the bot can navigate the shop for the user ("show me the vegetable boxes").agent— set for bot answers, empty for user messages (relevant in transcripts).
The transcript
chatscript1 returns the full conversation as a sequence of
ChatResponse objects, ordered by dt, with both the user's
messages (agent empty) and the bot's answers. Use it to restore the chat widget's history
after a page reload. A user only sees their own transcript; admins may look up any
conversation by chatid.
developing aid
A query starting with F: bypasses the bot and calls one of the internal AI command functions
directly, e.g. q=F:searchItems(searchterm:"bier") — useful to test the actions the bot can
trigger. Sending an unknown function name returns the list of available functions.
Getting started
- Probe availability:
GET <base>/api/chat1?oo-rf=json— check the ChatControl status. - Ask something:
GET <base>/api/chat1?q=...&oo-rf=json— renderdisplay, act onaction. - Keep the web session (cookie or
x-oekobox-sid) so follow-up questions stay in context. - On reload, restore history with
GET <base>/api/chatscript1?oo-rf=json.