Tool kit for custom connections

The tool kit is source code for your own connection to XICBOT, in three editions: Node (js/), PHP (php/) and Python (python/), each with four files. It contains a client for the API-key interface, a reader for the event stream of a chat reply, the signature check for webhooks and the lists of event types. It needs no further packages: Node calls via fetch, PHP via the curl extension, Python via the standard library. The last section covers the opposite direction: what your system has to answer when an assistant calls it as a tool.

What the kit contains

Each file names in its header the version of the interface description it was generated from, so you can tell which state of the API your copy reflects. The client loads the stream reader from the same directory (./strom.mjs, strom.php, from strom import Strom), so keep the files of one language together. The signature check and the event lists stand on their own and can be taken over individually, for example into a receiver that only accepts webhooks.

Address and key

The client takes two values: the base address https://app.xicbot.de and an API key. Trailing slashes on the base address are removed; the client appends the paths (/api/v1/integration/…) itself. If the base address is missing, all three editions stop with Basisadresse fehlt as soon as the client is created. The client sends the key in the X-Api-Key header. It starts with xbot_; a value without that prefix counts as missing.

Creating a key

1. 1

   Step 1

   Open the page

   Keys and webhooks are under Administration › Interfaces (app.xicbot.de/schnittstellen). The menu item appears for the Administration and Owner roles; only these roles create and revoke keys. The roles are described in Team, roles and audit log.

2. 2

   Step 2

   Choose name and scopes

   In the API keys section enter a Name of at most 80 characters and tick at least one scope under Scopes; until then Create a new key stays disabled. Below the scopes it says: “Writing is a separate scope. Without it a key only reads.”

3. 3

   Step 3

   Set limit and expiry

   Requests per minute is a required field from 1 to 6000, preset to 120. Expires in days accepts 1 to 3650; below it the page says “Empty means no expiry.” The expiry date is calculated from the number of days when the key is created.

4. 4

   Step 4

   Copy the key

   After Create a new key the card Your new key shows the value: xbot_ followed by 48 characters. Below it: “Copy it now. After closing it cannot be retrieved again.” The Copy key button puts it on the clipboard; if that fails, the page says “The clipboard is not available here. Select the value and copy it manually.” Of the key itself, XICBOT stores only a SHA-256 fingerprint and the Identifier, the first 12 characters.

The key list shows Name, Identifier, Scopes, Last used, Expires (no limit for keys without expiry), Status with valid, expired or revoked, and Action. Last used is updated at most once a minute. Next to the create button a counter shows the valid keys, for example 3 / 10. At most ten keys can be valid at the same time; the eleventh is refused with 422, too_many_keys and the message “The maximum number of simultaneous keys has been reached.” Revoked and expired keys do not count.

Revoke asks for confirmation in the row: “Revoke this key? Requests using it will be rejected from then on.” Confirm with Revoke or back out with Cancel. From then on the API answers this key with 401 and invalid_key; the row stays in the list with the status revoked. A key cannot be edited. For other scopes or another limit, create a new key, switch your system over and revoke the old one. More on managing keys is in API keys and webhooks.

Scopes

A writing scope does not include the reading one: leads.write creates enquiries but does not read them. GET /api/v1/integration/status returns alive, the account identifier in tenant, the key's scopes in scopes and its per-minute limit in limit_per_min. This lets you test a connection without reading any data. The individual requests are described in Integration endpoints.

Limits

Each key has its own per-minute cap, the value from Requests per minute. On top of that there is a daily cap from your account. It is counted per key and calendar day and expires at midnight, not 24 hours after the first request; a daily cap of 0 means no daily cap. Both caps are checked before either is counted, so a request rejected at a cap consumes nothing. GET /api/v1/integration/status counts as well. The level of the daily cap is given in the limit field of a 429 reply with scope day; GET /api/v1/integration/status only reports the per-minute cap as limit_per_min.

On 429 the client throws an error with the status and body of the response; you build retrying after retry_after yourself. The reply quota is separate: once it is used up for the month, the chat answers with 429 and quota_exhausted, see Chat and event stream. Overview of all limits: API limits.

The client

The client maps each operation of the API to a method of its own, named after the HTTP method and the path. You create it with the base address, the key and a timeout; the timeout limits every call whose reply arrives in one piece.

The Node and PHP editions set no timeout for chat, because the stream runs for as long as the reply is being produced. The Python edition reads the stream line by line and stops when a single read waits longer than stream_timeout for data, 120 seconds by default. Every request carries Content-Type: application/json, Accept: application/json and the key in X-Api-Key; for chat the client asks for text/event-stream instead.

If a required field is missing, the client stops before sending and raises Pflichtfeld fehlt: <field> as Error (Node), InvalidArgumentException (PHP) or ValueError (Python). When creating a knowledge source it also requires text or url and otherwise raises Eines der Felder fehlt: text oder url. XICBOT checks every other rule itself and answers a violation with 422. Conversations and enquiries are returned newest first, appointments by start time with the latest first. The three lists return 50 entries per call; page picks the page, counting from 1, and a missing or smaller value counts as 1. Keep reading until a page holds fewer than 50 entries. getAnalytics takes an IANA time zone in zone, default Europe/Berlin; XICBOT answers an unknown zone with 422 and unknown_timezone. A single conversation returns up to 200 messages in chronological order, each with role, text and time; an unknown ID is answered with 404 and not_found.

What XICBOT validates

XICBOT answers a new enquiry with 201, the entry under lead and duplicate_prevented: false, and sends the lead.created webhook at the same time. If the same external_id arrives a second time, no second entry is created: the reply is 200 with the existing entry and duplicate_prevented: true. After a timeout, resend with the same external_id. How enquiries are handled in the app is described in Appointments and cases.

A knowledge source with text is processed straight away; the reply is 201 with id, type (text), status and chunks under source, and knowledge.indexed or knowledge.failed is sent. The 201 also comes back when processing failed, so check status (ready means success). A source with url is created with 202 and, under source, id, type website and status new, and the page is fetched in the background. As when a source is created in the app, XICBOT also queues a background job for both kinds that enriches the sections and builds their vectors; after that, search usually finds the source by meaning as well, not only by matching words. Addresses that do not point to the public internet are rejected with 422 and the reason in error, for example target_not_allowed. More about sources is in Maintain knowledge.

Errors in the client

The text after the status is the body of the error reply, which XICBOT sends as JSON with an error field. The values are explained in the table under Address and key and in the chat section.

Chat and event stream

Each event consists of an event: <type> line, one or more data: <JSON> lines and a blank line. The kit's stream reader hands an event over only once the blank line has arrived, joins several data lines with a line break, strips a trailing \r and passes type and data to your function. If the content is not valid JSON, the data arrives as null (Python: None).

A conversation that started in the widget or in a test chat cannot be continued through the API, not even with the conversations scope; XICBOT answers with 404. How much the account may answer per month is described in Plans, quotas and billing.

Event types

With conversation_limit the notice text in English reads: “This conversation has reached its agreed length. I am handing it over to a person – please leave your question together with a way to reach you, or start a new conversation.” If the conversation is blocked for another reason, error is followed by the assistant's fallback reply and end with blocked.

import { Klient } from './klient.mjs';

const klient = new Klient('https://app.xicbot.de', process.env.XICBOT_KEY);
let antwort = '';

await klient.postChat({ assistant_id: 'ASSISTANT_ID', text: 'When are you open?' }, (art, daten) => {
	if (art === 'start') console.log('Conversation', daten.conversation_id);
	else if (art === 'text') antwort += daten.t;
	else if (art === 'redaction') antwort = daten.text;
	else if (art === 'error') console.error('Blocked:', daten.code);
	else if (art === 'end') console.log(antwort, daten.state);
	// any other type: skip
});

import os
from klient import Klient

klient = Klient('https://app.xicbot.de', os.environ['XICBOT_KEY'])
ergebnis = klient.post_leads({
    'subject': 'Call back about the quote',
    'email': 'customer@example.com',
    'external_id': 'crm-4711',
})
# 201 the first time, 200 with duplicate_prevented on a repeat
print(ergebnis['lead']['id'], ergebnis['duplicate_prevented'])

The structure of every operation is described in Integration endpoints; how conversations appear in the app is covered in Conversations.

Verifying webhooks

A webhook sends events from your account to an address on your system. You set it up on the same page as the keys, under Administration › Interfaces in the Webhooks section: “Every delivery carries a signature in the X-XICBOT-Signature header. Failed deliveries are retried.”

1. 1

   Step 1

   Enter the address

   Under Target address enter an address of at most 2048 characters. It has to point to the public internet; otherwise the page shows “This address is not permitted as a target.”

2. 2

   Step 2

   Choose events

   Under Events tick at least one. Create webhook stays disabled until the address and one event are set.

3. 3

   Step 3

   Copy the secret

   After creation the page shows Your signing secret once: whsec_ followed by 48 characters, with the note “Use it to verify the signature of an incoming delivery.” Use Copy secret to take it over into your system.

Each delivery is a POST with a JSON body of four fields: event (the event type), at (time of the event in ISO 8601 format, the same in every retry), tenant (your account ID) and data (the event payload). These headers come with it:

Checking the signature

1. 1

   Step 1

   Read the raw body

   The body is signed exactly as it arrives. Read it before any JSON processing; a body that is parsed and serialised again becomes a different string with a different signature.

2. 2

   Step 2

   Split the header

   The X-XICBOT-Signature header holds t and v1, separated by a comma. If either is missing or t contains anything other than digits, reject the delivery.

3. 3

   Step 3

   Check the age

   If t differs from your clock by more than 300 seconds, the kit rejects the delivery. The value is the hoechstalter parameter; 0 turns the check off, which lets a captured delivery be replayed any number of times.

4. 4

   Step 4

   Compute the signature

   HMAC-SHA256 over t, a dot and the raw body, with the signing secret as key, as a hex string.

5. 5

   Step 5

   Compare in constant time

   The kit compares with timingSafeEqual (Node), hash_equals (PHP) or hmac.compare_digest (Python). A comparison that stops early reveals through its running time how many characters already match.

<?php
require_once __DIR__.'/signatur.php';

$koerper = file_get_contents('php://input');
$kopf = $_SERVER['HTTP_X_XICBOT_SIGNATURE'] ?? '';
$geheimnis = (string) getenv('XICBOT_WEBHOOK_SECRET');

if (! xicbot_signatur_pruefen($koerper, $kopf, $geheimnis)) {
    http_response_code(401);
    exit;
}

$sendung = json_decode($koerper, true);
// evaluate $sendung['event'] and $sendung['data']
http_response_code(204);

Delivery and retries

• XICBOT waits up to 8 seconds for your reply. Any status from 200 to 299 counts as delivered; XICBOT does not follow redirects.
• A delivery goes to every webhook that is switched on and subscribed to the event.
• The address is checked when the webhook is created and again before each delivery.
• If an attempt fails, there are up to three attempts in total, usually after 30 and after 120 seconds. Each retry carries the same X-XICBOT-Delivery and the same at, a higher X-XICBOT-Attempt and a newly computed signature with a current t.
• Consecutive failures counts every failed attempt, including a delivery that the address check before sending already stops, and drops to 0 after a successful delivery. A signing secret that could not be read (secret_unreadable) does not count. At 20, XICBOT switches the webhook off and the row shows disabled. When you switch it back on, the count starts again at 0.
• The button in the row names the action: Turn off for a running webhook, Turn on for one that is switched off.
• Deliveries shows the last 50 attempts with Time, Events, Attempt, Status and Duration in milliseconds. Delete asks first: “Delete this webhook? Deliveries to this address stop immediately, and the signing secret cannot be restored.” The webhook address is shown below. The webhook is only deleted with Delete in the dialog; Cancel keeps it.

The Status column shows the status of your reply or one of these reasons:

Events

RUECKRUF_EREIGNISSE in the kit holds the same ten types. Keys and webhooks from the administration side are covered in API keys and webhooks.

When XICBOT calls your system

An assistant can call your system as a tool. Tools are set up per assistant under Triggers › Tools: with the Type Own interface for a free-form call, or with a type that speaks a fixed format, for example Read free slots. Approval, minimum role and required details are covered in Create and approve tools.

XICBOT does not accept fields named tenant_id, mandant, mandant_id or konto_id: a tool with such a field cannot be saved. Your system receives only the fields declared in the tool; anything else the assistant sends is dropped.

Own interface

With the Own interface type, XICBOT sends a POST with content-type: application/json and accept: application/json to the stored address. The body has three fields: tool (the tool's Key), input (the declared fields) and conversation_id. Strings in input are cut to 2000 characters, lists to 50 entries and nesting to three levels. No idempotency-key header is sent with this call.

{
  "tool": "delivery_time",
  "input": { "postcode": "10115" },
  "conversation_id": "9d1c…"
}

XICBOT passes the status of your reply to the assistant as status. If the reply is a JSON object or a JSON array, it arrives as data; any other reply is passed on as text, cut to 2000 characters. You decide which fields your JSON carries.

Types with a fixed format

The other types that talk to an external system send a fixed envelope with seven fields and expect a fixed reply. Writing operations also carry the idempotency-key header: 64 hex characters derived from conversation, tool and input. A repeated call with the same input in the same conversation carries the same value, so your system can recognise it as a repeat. Reading operations do not carry it.

{
  "ok": true,
  "data": {
    "slots": ["2026-10-06T09:00", "2026-10-06T10:30"],
    "timezone": "Europe/Berlin",
    "note": "Saturdays mornings only"
  }
}

From data XICBOT takes only the result fields of the type, for Read free slots that is slots, timezone and note. Strings are cut to 600 characters, lists to 20 entries and nesting to two levels. To decline, your system replies with "ok": false and a reason in error; XICBOT keeps up to 200 characters of it. If ok is missing, the reply counts as a breach of the format.

Call limits

A call that succeeds is recorded in the history as executed. If the waiting time runs out it shows as timed out; any other error shows as failed with the message, cut to 500 characters. XICBOT records the duration of each call in milliseconds. A redirect also ends as failed. XICBOT does not retry a failed call on its own. These messages can appear:

Whether a call runs straight away or only after the visitor confirms it is set by Approval: without asking or with confirmation. Own interface is preset to with confirmation. A reading tool set to without asking runs straight away, as does the query for free slots with Book appointment; XICBOT stores a writing tool with with confirmation whatever was chosen. If a required input field is missing, the call ends as failed before your system is contacted. Details are in Create and approve tools.

Frequent questions