Integration endpoints

The integration API connects your own systems to XICBOT. With an API key you read conversations, enquiries, appointments and metrics, create enquiries and knowledge sources, and put questions to an assistant, with the reply streamed back as server-sent events. Every endpoint lives under /api/v1/integration/ and checks the key's scope on its own.

Overview

The base address is https://app.xicbot.de/api/v1/integration/. Each request carries the key in the X-Api-Key header; keys start with xbot_. Creating a key, choosing its scopes and letting it expire is covered in Keys and webhooks, the authentication scheme in Authentication. These endpoints sit outside the app's session login, so a session token does not open them.

Writing is a scope of its own: a key with leads reads enquiries but cannot create any. Under Scopes the app puts it this way: *Writing is a separate scope. Without it a key only reads.*

Errors every endpoint shares

Before an endpoint does its actual work, the API checks the key, the account, the plan, the rate caps and the scope. Errors come back as JSON with an error field.

Rate limits

Every key has a per-minute cap, which you enter under Requests per minute when creating it, and a daily cap from your account settings; both are counted per key. Once either is reached, the endpoint answers 429 with too_many_requests. Values, time windows and the response fields are in API limits.

Paging

The lists of conversations, enquiries and appointments return 50 entries per page. Conversations and enquiries are ordered by creation time, newest first; appointments by start time, latest first. Pick the page with page, counting from 1; a missing or smaller value counts as 1, and a value that is not a whole number is rejected with 422. The response echoes the page in page and gives no total. Keep reading until a page holds fewer than 50 entries.

Status

curl -s https://app.xicbot.de/api/v1/integration/status \
  -H "X-Api-Key: $XICBOT_KEY"

# {"alive":true,"tenant":"…","scopes":["leads","leads.write"],"limit_per_min":120}

Conversations

Enquiries

Enquiries are contact requests. They arise in a conversation with an assistant or through this API. When an assistant creates an enquiry through a tool, that also fires the lead.created webhook, with a different payload from the one here, see Webhooks triggered. In the app you handle enquiries under Appointments and cases.

Appointments

Metrics

The window includes the current day and ends at the next midnight in the given zone: 7d covers today and the six days before it.

Creating knowledge sources

Whether a website fetch succeeded is reported by the knowledge.indexed and knowledge.failed webhooks. On failure, reason holds a named cause such as no_text_extracted, url_unreachable, website_too_large or redirect_off_origin; other causes show up as ingest_failed. The fetch gets up to three attempts, and every failed attempt sends knowledge.failed. You may therefore receive several events for the same source_id, including a knowledge.indexed after a knowledge.failed; the most recent one counts.

Chat

The quota is explained in Plans and quotas. A conversation runs at most one reply at a time; if a run breaks off, the conversation is free again after 180 seconds. A conversation marked as done in the app can be continued too, and the question reopens it: if it had been handed over (escalated_at set), it becomes escalated with a new escalated_at and is back in the inbox; otherwise it becomes open; resolved_at is cleared. No event is sent for this, and a rejected question reopens nothing. A new conversation records as its origin the host from the Origin or Referer header if your call sends one; otherwise the origin stays empty.

Event stream

The response has the type text/event-stream; charset=utf-8 and is delivered uncached (Cache-Control: no-cache, no-store). Each event is an event: line with its type and a data: line with a JSON object, followed by a blank line. The ID of a new conversation arrives in the first event, start; keep it for follow-up questions.

curl -N https://app.xicbot.de/api/v1/integration/chat \
  -H "X-Api-Key: $XICBOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistant_id": "…", "text": "What are your opening hours?"}'

event: start
data: {"conversation_id":"…","question_id":null}

event: text
data: {"t":"We are open Monday "}

event: text
data: {"t":"to Friday."}

event: end
data: {"state":"done","message_id":"…",…}

Webhooks triggered

The endpoints of this API fire the following webhooks, provided you have set up a receiver for the event, see Keys and webhooks. All events with every trigger, including those outside the integration, are listed under Events.

Frequent questions