← API Index

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:

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:

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

  1. Probe availability: GET <base>/api/chat1?oo-rf=json — check the ChatControl status.
  2. Ask something: GET <base>/api/chat1?q=...&oo-rf=json — render display, act on action.
  3. Keep the web session (cookie or x-oekobox-sid) so follow-up questions stay in context.
  4. On reload, restore history with GET <base>/api/chatscript1?oo-rf=json.