Widget endpoints

The chat window talks to the service through 14 endpoints under https://app.xicbot.de/api/v1/public/widget/{key}. They require no sign-in: the widget key in the path selects the assistant, and the conversation ID returned when a conversation starts ties every further call to that conversation. This page describes each endpoint with its request fields, response and errors. How the chat window uses them is shown in Chat in the widget; endpoints outside the widget are listed under Public endpoints.

Overview

The paths in the table follow https://app.xicbot.de/api/v1/public/widget/{key}. The address, the error format and the rules for calls from the browser are described in API basics, the throttle counters in API limits.

Common rules

Key in the path

The key {key} is the value of the data-xicbot attribute in the embed code: 16 random bytes written as 32 characters from 0 to 9 and a to f. It is not a secret, since it appears in the source of every page that shows the widget. The service checks the key before every endpoint and otherwise responds as follows:

A new key is created by POST /api/v1/assistants/{id}/key with the admin role, see API authentication. The service logs the change first. If that fails, it responds with 500 and not_logged, and the current key stays in place. Otherwise the new value is returned in key, and the old key yields unknown_widget from then on. Replace the embed code on every page afterwards, see Public key.

Throttles and caps

Two layers limit the endpoints. The named throttle counts per visitor, formed from the visitor’s IP address (the first 64 bits for IPv6) and the widget key: widget allows 60 and widget-send 12 calls per minute, see Limits per visitor. Behind it, the service checks the widget caps, whose values belong to the account.

• The call cap applies to settings, start, history, withdrawal, rating, data export, deletion, to confirming, rejecting and reporting a tool call, and to uploading, listing and downloading attachments. The defaults are 60 calls per minute and 2000 per day.
• The question cap applies only to POST send. The defaults are 10 questions per minute and 200 per day.
• Each cap counts on the visitor and, if the call names a conversation, also on that conversation. The conversation is taken from the path or from conversation_id in the body. Either counter can reject; counting only happens once neither has rejected.
• The windows are 60 seconds and 86,400 seconds. A cap below 1 is switched off.

When a cap rejects a call, the response is 429 with this body and the Retry-After header:

Conversation ID

Starting a conversation returns conversation_id, a UUID. POST send and every endpoint with {conversation} in the path look up the conversation by this ID, the assistant of the key and the widget channel. If any of these does not match, the response is 404 with not_found. A conversation of another assistant or from another channel is therefore out of reach through the widget. The IDs of messages, tool calls and attachments are UUIDs as well and are only looked up within the conversation named in the path.

Calls from the browser

The CORS rules under /api/v1/public/ admit the origin null. The chat window runs in a frame with sandbox="allow-scripts" and without allow-same-origin, and such a frame sends Origin: null. Which sites may start a conversation is decided not by CORS but by the domain list when a conversation starts. Methods, headers and the preflight lifetime are listed in API basics.

Errors

Errors arrive as JSON with a code in error; some endpoints add further fields, listed in the tables below. Validation of the request fields responds with 422, a text in message and a list per field in errors, see Error format. Evaluate the code, not the text. Once the answer stream of POST send has started, it reports errors as events rather than as a status.

Fetching the settings

With host and without preview, the service records the time and host name of the embedding, at most once every 300 seconds for the same host name. This endpoint does not check host against the domain list; that only happens when a conversation starts.

language only affects the texts the service supplies itself: note, limit_notice and the default consent text. The greeting and outreach messages stay as written in the assistant. Without a valid preference, en applies if the active version of the assistant is English, otherwise de.

The response is a JSON object with these fields:

The default consent text is “I agree that my conversation is stored and processed in order to answer my question.” The attachment limits are part of the response so that the chat window can reject a file that is too large before uploading it.

forms holds at most 10 entries, ordered by tool key: only active form-fill tools that the public role may use. It contains no values; the chat window only writes into the listed fields. Setup is described in Form prefill, the rules behind outreach_rules in Outreach rules.

Starting a conversation

The service checks in this order and stops at the first failure:

1. 1

   Step 1

   Validate the fields

   Invalid fields return 422 with message and errors.

2. 2

   Step 2

   Active version

   If the assistant has no active version, the response is 422 with no_version.

3. 3

   Step 3

   Call cap

   If the cap is reached, 429 with too_many_requests follows.

4. 4

   Step 4

   Domain list

   If host does not match the domain list, the response is 403 with host_not_allowed.

5. 5

   Step 5

   Block list

   If the visitor’s IP address is blocked, 403 with blocked follows.

6. 6

   Step 6

   Consent

   If the assistant requires consent and consent: true is missing, the response is 422 with consent_missing. If a consent_text sent along matches no current consent text, 422 with consent_changed follows; consent_text then carries the current text in the language selected by language. These checks run before creation: without the required consent, the service does not create a conversation.

7. 7

   Step 7

   Create

   Only now does the service create the conversation with status open and respond with 201.

If the assistant’s domain list is empty, any site may start a conversation. If it has entries, host must be present and either equal an entry or end with a dot followed by an entry: the entry example.com also covers shop.example.com. Entries are separated by a comma or a line break and compared in lower case. You maintain the list under Allowed domains.

Blocked visitors can no longer create a conversation; the block applies before a conversation is created. How to block visitors is described in Blocking visitors.

If the assistant requires consent, the conversation stores the time in consent_at and a check value in consent_hash. The check value is a SHA-256 over the consent text the visitor sees in the selected language, the privacy notice version and the host name. That is the assistant’s custom text, otherwise the default text for the language. If you send the wording shown in consent_text, the language whose text it matches applies. Without it, language selects the language as when fetching the settings; without a valid preference, en applies if the active version is English, otherwise de. In that case, send the same preference at the start as when fetching the settings: if the default text applies, the check value would otherwise record the wording of a different language than the one shown. Consent is thus tied to the conversation and not to a value in the browser. More in Consent.

After creating the conversation, the service fires the conversation.started webhook with conversation_id, assistant_id and channel.

Sending a question

If the account has a length cap below 4000 characters, that cap applies. The question is stored before the stream begins. If the conversation is closed, the stored question reopens it: if it had been handed over (escalated_at set), it becomes escalated with a new escalated_at, otherwise open; resolved_at is cleared. No event is sent for this, and a rejected question reopens nothing. At most one answer runs per conversation; the service claims the conversation with a conditional update. If a run does not end cleanly, the claim releases the conversation after 180 seconds.

curl -N https://app.xicbot.de/api/v1/public/widget/0123456789abcdef0123456789abcdef/send \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"conversation_id":"9d1f6c2a-3b4e-4f5a-8c7d-1e2f3a4b5c6d","text":"I have a question about my order."}'

Event stream

After the checks, the endpoint responds with status 200, Content-Type: text/event-stream; charset=utf-8 and Cache-Control: no-cache, no-store. Each event consists of an event: line with the name, a data: line with a JSON object and a blank line. Non-ASCII characters and slashes appear unescaped in the JSON. The chat window sends Accept: text/event-stream for this call. How it renders the events is described in Answer stream.

citations, contact_offer, follow_ups, handoff with assistant, redaction, verification and enforcement only arrive when the answer runs to its regular end. A shortened stream looks like this:

event: start
data: {"conversation_id":"9d1f6c2a-3b4e-4f5a-8c7d-1e2f3a4b5c6d","question_id":null}

event: text
data: {"t":"I am happy to help "}

event: text
data: {"t":"with your order."}

event: verification
data: {"state":"no_claims","claims":[],"total":0}

event: enforcement
data: {"state":"clear","topics":[],"handover":false}

event: end
data: {"state":"done","message_id":"4b8e2f10-6c3d-4a5e-9f7b-2d1c0e9a8b76","refused":false,"citations":[]}

Special cases

In each of these cases the question has been stored before the stream begins.

• Takeover: If a staff member has taken over the conversation, start is followed only by live and by end with state set to live and message_id set to null. The staff member writes the answer, see Taking over.
• Quota exhausted: error follows with code set to quota_exhausted, scope set to month and retry_after in seconds until the start of next month, then the fallback reply as text and end with blocked. The status stays 200; a 429 for the quota only exists in the integration API channel. See Quota exhausted.
• Conversation cap: If the visitor has already asked as many questions in this conversation as the account cap allows, error follows with conversation_limit and limit, a notice as text, handoff with conversation_limit and end with blocked. The default is 60 questions; the value 0 switches the cap off.
• Fault: During a transient fault, model_switch may arrive and the answer continues. If it fails, fallback, the fallback reply as text and end with fallback follow.
• Withdrawal during the run: For conversations with consent, the run checks at most once per second, and once more at the end, whether consent has been withdrawn. If so, it discards the answer and sends revoked and end with revoked.
• Answer from a question and answer pair: If the question matches an active pair, no model is asked. start is followed by the pair's answer in a single text, citations with exactly one citation (the pair's question as document, chunk_id made of qa: and the pair's ID) and enforcement; if the question touches a restricted topic or a taboo, redaction with notice, a notice as another text and handoff may follow. Finally end arrives with done. There is no verification, follow_ups or contact_offer in this case. See Question and answer pairs.
• Post-processing: redaction replaces the text shown. With claims, unsupported statements are replaced by the placeholders [nicht belegt] or [not backed]; with notice, the topic check has rewritten the text. After enforcement, a notice may follow as another text, as may a notice about unsupported statements if the assistant may only answer from its knowledge.

message_id is the ID of the stored answer; you use it to rate the answer. If nothing was stored, the value is null. refused is true only with done, when the assistant declined the question. citations lists the sources of the run.

Loading the history

The response contains messages and taken_over. messages consists of the latest 50 messages and the latest 50 tool calls, sorted together in ascending order of time. taken_over is true while a staff member has taken over the conversation. If the conversation is unknown, the response is 404 with not_found.

Withdrawing consent

The response is {"revoked": true, "run_aborted": …}. run_aborted is true if the conversation was claimed for an answer at that moment; a running answer is then discarded and its run ends with revoked. The withdrawal is set once: a second call returns the same response and does not change the time. More in Withdrawing consent.

Withdrawal, data export and deletion remain open to blocked visitors as well; the service checks the block list only when starting, sending and uploading an attachment.

Rating an answer

The cap is checked before the fields. The service stores the time together with the rating; null clears both. How the chat window shows the buttons is described in Rating.

Data export

Times use the ISO 8601 format. More on the visitor’s rights in Access request.

Deleting a conversation

The deletion is logged first: the log entry with the trigger visitor and the counts is written in the same database transaction as the deletion and before it. If no entry can be written, the service deletes nothing and responds with 500 and not_logged. What is deleted along with the conversation is described in What goes with a conversation.

Tool calls

When the assistant proposes a step that changes something, or calls a read-only tool whose approval is with confirmation, the stream carries a tool event with state set to proposed and needs_confirmation set to true. The step only runs once the visitor confirms it: the confirm endpoint is the only way a changing tool runs in the widget; the answer run itself only executes reading tools. The cards in the chat window are described in Tool cards, the tools themselves in Tools.

The event, the history, the data export and the endpoints in this section show a call in the same brief form:

The widget does not expose the duration or approval path of a call, nor the note and email_notified fields of the result. At most 5 tool calls run per answer; a further one ends with failed and chain_capped set to true.

Confirming a call

First the service sets a proposal older than 60 minutes to expired. It then moves the call from proposed to confirmed with a conditional update; of two simultaneous clicks only one wins. On the click it checks again whether the tool still exists, whether role and plan allow it and whether the required fields are filled; otherwise the call ends with failed. Execution ends with executed, timeout or failed.

duplicate is true if the call had already been decided or another click won; the step then does not run a second time. call shows the current state in every case, including expired.

Rejecting a call

Reporting a form fill

The body is JSON. Without a JSON header the service reads the raw body up to 16384 bytes and decodes it as JSON; this lets the loader script send the report as text/plain with keepalive. Such a request needs no preflight and survives leaving the page, for example when the form navigates away on submit.

The report is a statement from the customer's page. Only field names that appear in the instruction of this call are kept. It is stored as report with filled, missing, blocked, submitted and form_found; submitted is only true if the instruction included submitting and abgesendet is true. The first report per call is accepted; any further one gets duplicate set to true and the report already stored. What the form fill enters is described in Form prefill.

Attachments

Visitors can attach images and PDF files to a conversation if the assistant allows it; this is switched on under Visitor files. How the visitor experiences this in the widget is described under Attachments in the chat. Besides the named throttle, all three endpoints count against the call cap.

The service determines the type from the file content, not from the extension or the browser's claim: PNG, JPEG, WebP and PDF are recognised by their first bytes, everything else is rejected. It also measures the size on the received file.

Uploading an attachment

The service strips slashes, backslashes, quotes and control characters from the file name, keeps only the last path segment and truncates to 120 characters. If nothing is left, the file is named anhang.png, anhang.jpg, anhang.webp or anhang.pdf.

If the conversation already has a contact request, the attachment is linked to the most recent one right away; lead_id then carries its ID. If the request only comes later, it takes over all attachments of the conversation whose lead_id is still empty. The upload is usually recorded in the activity log with type and size; if that entry cannot be written, the attachment is stored anyway and the response is 201.

The checks run in the order of the table; the first one that applies determines the response. The four rejections from checking the file (upload_failed, too_large, too_many and type_not_allowed) also carry max_bytes, types and max_per_conversation so the widget can tell the visitor the limits.

curl -X POST \
  https://app.xicbot.de/api/v1/public/widget/0123456789abcdef0123456789abcdef/conversation/9d1f6c2a-3b4e-4f5a-8c7d-1e2f3a4b5c6d/attachment \
  -F 'file=@schaden.jpg'

Listing attachments

Downloading an attachment

Frequent questions