Interactive Messages

Interactive Messages sind WhatsApp Buttons und Listen, die der Bot im Gesprächsablauf senden kann. Jeder Block wird in bot_interactive_blocks gespeichert und kann über das Flow-System einem Step zugeordnet werden.

Block-Typen

block_type	Beschreibung	Items	WhatsApp-Darstellung
buttons	Reply Buttons	1–3	Buttons unter der Nachricht
list	Interaktive Liste	1–10	Aufklappbare Liste mit Einträgen

Trigger-Modi

Der trigger_mode bestimmt, wann und wie der Bot den Block sendet:

trigger_mode	Beschreibung
checkpoint	Block wird an einem definierten Checkpoint im Gespräch ausgelöst
mandatory	Bot MUSS den Block senden wenn der Flow-Step erreicht wird
optional	Bot ENTSCHEIDET selbst ob der Block zum Kontext passt

Endpoints

Alle Endpoints erfordern Auth + Tenant-Check. Basis-Pfad: /api/bots/:botId/blocks

Methode	Pfad	Beschreibung
GET	/	Alle Blöcke eines Bots laden (sortiert nach sort_order, mit Checkpoint-Info)
GET	/:blockId	Einzelnen Block laden
POST	/	Neuen Block erstellen
PUT	/reorder	Reihenfolge ändern
GET	/hybrid-prompt	Hybrid-Flow Prompt generieren
PUT	/:blockId	Block aktualisieren
DELETE	/:blockId	Block löschen

Route-Reihenfolge

/reorder und /hybrid-prompt sind VOR /:blockId definiert (spezifisch vor generisch).

Validierungslimits

Felder

Feld	Max. Zeichen	Pflicht	Beschreibung
block_name	50	Ja	Technischer Name (nur [a-z0-9_])
display_name	100	Ja	Anzeigename
body	1024	Ja	Nachrichtentext
header	60	Nein	Kopfzeile
footer	60	Nein	Fußzeile
button_text	20	Nein (Listen)	Button-Text zum Öffnen der Liste
ai_hint	255	Nein	Hinweis für die KI, wann der Block passt (nur bei trigger_mode='optional')

Items (Buttons)

Eigenschaft	Limit
Mindestanzahl	1
Maximalanzahl	3
Titel max. Zeichen	20

Items (Liste)

Eigenschaft	Limit
Mindestanzahl	1
Maximalanzahl	10
Titel max. Zeichen	24
Beschreibung max. Zeichen	72

Item-Struktur

Jedes Item benötigt mindestens id (String) und title (String). Bei Listen optional description.

WhatsApp API Limits

Diese Limits kommen direkt von der WhatsApp Business API und werden durch DB-Check-Constraints erzwungen:

Constraint	Regel
valid_block_type	Nur buttons oder list
valid_items_buttons	1–3 Items bei block_type='buttons'
valid_items_list	1–10 Items bei block_type='list'
valid_trigger_mode	Nur checkpoint, optional oder mandatory
valid_block_name	Regex ^[a-z0-9_]+$

Datenbank-Schema

bot_interactive_blocks

Spalte	Typ	Nullable	Default	Beschreibung
id	uuid	NOT NULL	gen_random_uuid()	Primary Key
tenant_id	uuid	NOT NULL	—	FK auf tenants
bot_id	uuid	NOT NULL	—	FK auf bots (CASCADE DELETE)
block_name	varchar(50)	NOT NULL	—	Technischer Name (lowercase, unique pro Bot)
display_name	varchar(100)	NOT NULL	—	Anzeigename
block_type	varchar(10)	NOT NULL	—	buttons oder list
header	varchar(60)	NULL	—	Kopfzeile
body	varchar(1024)	NOT NULL	—	Nachrichtentext
footer	varchar(60)	NULL	—	Fußzeile
button_text	varchar(20)	NULL	—	Button-Text (nur Listen)
items	jsonb	NOT NULL	'[]'	Array von Items mit id, title, optional description
trigger_mode	varchar(15)	NOT NULL	'optional'	checkpoint, mandatory oder optional
checkpoint_id	uuid	NULL	—	FK auf bot_checkpoints
checkpoint_condition	jsonb	NULL	'{}'	Bedingung für Checkpoint-Auslösung
ai_hint	varchar(255)	NULL	—	KI-Hinweis (nur bei optional)
sort_order	integer	NULL	0	Sortierreihenfolge
is_active	boolean	NULL	true	Aktiv/Inaktiv
created_at	timestamptz	NULL	CURRENT_TIMESTAMP	Erstelldatum
updated_at	timestamptz	NULL	CURRENT_TIMESTAMP	Änderungsdatum
trigger_condition	text	NULL	—	Zusätzliche Auslösebedingung

Unique Constraint: (bot_id, block_name) — ein Block-Name pro Bot.

Indizes:

• idx_interactive_blocks_bot — btree auf (bot_id, is_active)
• idx_interactive_blocks_checkpoint — btree auf (checkpoint_id)
• idx_interactive_blocks_tenant — btree auf (tenant_id)

Fehlerbehandlung

HTTP Status	Situation
400	Validierungsfehler (Felder, Items, Limits)
404	Block oder Checkpoint nicht gefunden
409	Block-Name existiert bereits für diesen Bot (Unique Constraint)
500	Interner Fehler