# Fleißbots Bot-API — Referenz für KI-Assistenten und Entwickler

> Fleißbots (https://fleissbots.adlx.de) ist der Leitstand für Automatisierungen, Workflows
> und Agenten: Bots beobachten Systeme, melden das Wichtige als Chat-Nachricht in die
> Fleißbots-App (iOS) und fragen bei Entscheidungen per Schaltflächen nach. Diese Datei
> beschreibt die komplette Bot-API. Ein "Fleißbot" ist alles, was einen HTTP-POST senden
> kann: n8n-Workflow, Make-Szenario, Cron-Skript, Agent.

Aufgabe für dich (KI-Assistent): Wenn dein Nutzer einen Fleißbot bauen will, erzeuge mit
dieser Referenz den passenden Workflow oder das passende Skript. Frage nach, welches
Werkzeug er nutzt (n8n, Make, Shell, Node, Python, …) und wo das Bot-Token liegt.
Das Token gehört in eine Umgebungsvariable oder einen Credential-Speicher, nie in Code.

## Grundlagen

- Basis-URL: https://api.fleissbots.adlx.de
- Authentifizierung: HTTP-Header `Authorization: Bearer <BOT_TOKEN>` (ein Token pro Bot;
  gibt es bei ADLX, info@adlx.de — serverseitig nur als Hash gespeichert)
- Alle Bodies sind JSON (`Content-Type: application/json`)
- Rate-Limits: bei HTTP 429 mit Backoff erneut versuchen
- Zwei Betriebsarten, kombinierbar:
  1. PROAKTIV: Bot sendet von sich aus (Monitoring, Digest, Report) — braucht KEINEN
     erreichbaren Webhook, nur die zwei Aufrufe unten.
  2. REAKTIV: Bot empfängt Nutzer-Nachrichten/Schaltflächen-Antworten an seiner
     Webhook-URL (HMAC-signiert) und antwortet asynchron über die Sende-API.

## 1. Konversationen abrufen (Ziele für proaktives Senden)

GET /api/v1/bot/conversations
Authorization: Bearer <BOT_TOKEN>

Antwort 200:
[
  {
    "conversation_id": "uuid",        // in POST /api/v1/bot/messages einsetzbar
    "user": { "id": "uuid", "display_name": "Steffen Adler" },
    "updated_at": "2026-08-19T09:30:00.000Z"
  }
]

Je Nutzer im Leitstand (Tenant) existiert genau eine Konversation mit dem Bot.
Soll nur eine bestimmte Person Meldungen bekommen, nach `user.id` filtern —
sonst an alle Konversationen senden.

## 2. Nachricht senden

POST /api/v1/bot/messages
Authorization: Bearer <BOT_TOKEN>

Body (JSON):
{
  "conversation_id": "uuid",             // Pflicht
  "type": "text",                        // Pflicht: text | image | file | audio | buttons
  "text": "…",                           // Markdown-Teilmenge: fett, kursiv, Links, Listen
  "attachment_url": "https://… oder data:…",  // bei image/file/audio; s. Anhänge
  "attachment_name": "bericht.pdf",      // optionaler Dateiname
  "buttons": [                           // bei type "buttons"
    { "id": "freigeben", "label": "Freigeben" },
    { "id": "pruefen",   "label": "Prüfen lassen" }
  ],
  "priority": "normal"                   // normal (Default) | critical
}

Antwort: 202 (angenommen, wird an die Geräte verteilt). Push-Zustellung inklusive.
`priority: "critical"` → zeitkritische Mitteilung auf iOS (durchbricht Fokus-Modi).
Nur für echte Dringlichkeit verwenden.

### Anhänge

- `attachment_url` wird SERVERSEITIG vom Gateway heruntergeladen und im eigenen
  EU-Storage abgelegt; die App sieht nie fremde URLs. Die Quelle muss also nur für
  das Gateway erreichbar sein — oder gar nicht gehostet werden:
- `data:`-URIs funktionieren. Beispiel vCard direkt aus dem Workflow:
  {
    "conversation_id": "…",
    "type": "file",
    "text": "Neuer Kontakt: Max Beispiel (Beispiel GmbH)",
    "attachment_url": "data:text/vcard;base64,QkVHSU46VkNBUkQ…",
    "attachment_name": "max-beispiel.vcf"
  }
- `type: "file"` MIT `text` ist erlaubt und empfohlen: Die App zeigt Anhang und
  Begleittext zusammen an.

## 3. „tippt …"-Hinweis (optional)

POST /api/v1/bot/typing
Authorization: Bearer <BOT_TOKEN>
Body: { "conversation_id": "uuid" }

Zeigt dem Nutzer flüchtig „tippt …" (kein Persistieren, kein Push). Sinnvoll, wenn
zwischen Webhook-Empfang und Antwort spürbar Zeit vergeht.

## 4. Eingehende Nachrichten empfangen (Webhook, nur für reaktive Bots)

Das Gateway POSTet an die beim Bot hinterlegte Webhook-URL:

Header:
  content-type: application/json
  x-adlx-signature: <hex>        // HMAC-SHA256 über den ROHEN Body, Key = Webhook-Secret
  x-adlx-tenant: <tenant_id>
  x-adlx-conversation: <conversation_id>

Body:
{
  "message_id": "uuid",
  "conversation_id": "uuid",
  "tenant_id": "uuid",
  "user": { "id": "uuid", "display_name": "…" },
  "timestamp": "2026-08-19T09:30:00.000Z",
  "type": "text",                // text | button_reply | image | file | audio
  "text": "…",
  "button_reply": {              // nur bei type "button_reply"
    "id": "pruefen",             // die Button-id aus der Schaltflächen-Nachricht
    "label": "Prüfen lassen",
    "in_reply_to": "uuid"        // message_id der Schaltflächen-Nachricht
  },
  "attachment": { "url": "…" }   // nur bei Medien; kurzlebige Download-URL
}

Regeln:
- Signatur IMMER prüfen (Beispiel Node.js):
    const crypto = require('crypto');
    const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
                           .update(rawBody).digest('hex');
    const ok = crypto.timingSafeEqual(Buffer.from(expected),
                                      Buffer.from(req.headers['x-adlx-signature']));
- Schnell mit HTTP 200 antworten; bei Fehlern wiederholt das Gateway mit Backoff.
- Die inhaltliche Antwort NICHT als HTTP-Response liefern, sondern asynchron über
  POST /api/v1/bot/messages senden.
- `attachment.url` ist kurzlebig (presigned): sofort herunterladen, nie speichern
  oder weiterreichen.
- Schaltflächen sind One-Shot: Nach einem Tap sind sie verbraucht. Für eine erneute
  Auswahl eine frische buttons-Nachricht senden.

## Muster

### Proaktiver Melder (Cron → Fleißbots), Shell:
  CONVS=$(curl -s https://api.fleissbots.adlx.de/api/v1/bot/conversations \
    -H "Authorization: Bearer $BOT_TOKEN")
  echo "$CONVS" | jq -r '.[].conversation_id' | while read -r CID; do
    curl -s https://api.fleissbots.adlx.de/api/v1/bot/messages \
      -H "Authorization: Bearer $BOT_TOKEN" -H "Content-Type: application/json" \
      -d "{\"conversation_id\":\"$CID\",\"type\":\"text\",\"text\":\"Nachtlauf ok: 12 Aufgaben erledigt.\"}"
  done

### Freigabe-Bot (nachfragen → entscheiden lassen → handeln):
  1. Ereignis erkannt → buttons-Nachricht senden ("Freigeben" / "Prüfen lassen")
  2. Webhook empfängt type "button_reply" mit id "freigeben" oder "pruefen"
  3. Workflow verzweigt entsprechend und meldet das Ergebnis als text-Nachricht

### Digest statt Einzelmeldungen:
  Ereignisse sammeln (z. B. in einer Tabelle/staticData), einmal täglich zur festen
  Uhrzeit EINE Nachricht senden: "Heute 40 Ereignisse, davon 3 wichtig: …".
  Faustregel: Ein Fleißbot liest zweihundert Meldungen, der Nutzer liest vier Zeilen.

## Verhaltensregeln für gute Fleißbots

- Melde wenig und Wichtiges; bündele Routine in Digests. Ständige Pings führen zur
  Stummschaltung.
- `priority: "critical"` nur, wenn sofortiges Handeln nötig ist (Ausfall, Fehllauf,
  harte Frist).
- Formuliere Meldungen als Entscheidungsvorlage: Was ist passiert, was bedeutet es,
  was ist zu tun. Uhrzeiten und Zahlen statt Adjektiven.
- Bei Entscheidungen: nachfragen (buttons), nicht eigenmächtig handeln. Eingreifen
  tut der Mensch.
- Keine Geheimnisse (Tokens, Passwörter) in Nachrichtentexte schreiben — Nachrichten
  werden nach 30 Tagen automatisch gelöscht, sind bis dahin aber auf allen Geräten
  des Empfängers sichtbar.

## Mail-Bridge (ohne Code)

Jeder Bot kann eine geheime E-Mail-Einliefer-Adresse bekommen
(<localpart>@mail.fleissbots.adlx.de). E-Mails an diese Adresse werden geprüft und als
Bot-Meldung zugestellt — der schnellste Weg, ein bestehendes System (Asana, Shop,
Buchhaltung) melden zu lassen: dort einfach eine Weiterleitung einrichten.

- Angenommen wird nur, was BEIDES erfüllt: Absender steht auf der Freigabeliste der
  Adresse (exakte Adresse oder Domain) UND die Mail besteht SPF oder DKIM.
- Übernommen werden Absender, Betreff, Textauszug. Anhänge und vollständige Header
  werden verworfen. Nicht Angenommenes wird sofort gelöscht (nur Zähler).
- Modi: sofort zustellen oder Tages-Digest (eine Meldung zur Wunschstunde).
- Anlegen: im Chat über den ADLX-Bot (nach der Bot-Anlage) oder über ADLX
  (info@adlx.de). Die Adresse ist ein Geheimnis und kann rotiert werden.

## Betrieb & Datenschutz (Kurzfassung)

- Hosting in Deutschland, Daten bleiben in der EU. DSGVO-konform, AVV verfügbar.
- Push-Mitteilungen enthalten nie Klartext-Inhalte; das Gerät lädt Inhalte selbst nach.
- Nachrichten und Anhänge werden nach 30 Tagen automatisch gelöscht.
- Bot-Token und Einladungscodes werden serverseitig nur als SHA-256-Hash gespeichert.

## Kontakt

- Bot-Zugang / Token: info@adlx.de (Betreff "Bot-Zugang")
- Menschlich lesbare Doku: https://fleissbots.adlx.de/entwickler/
- App (iOS): https://apps.apple.com/de/app/id6788885660