Expert Guide: Ticketsysteme & GraphQL-Schnittstellen anbinden

Die automatische Abfrage von freien Plätzen, Startzeiten und Preisen gehört zu den anspruchsvollsten Service-Anwendungsfällen bei Ticket- und Event-Plattformen. Während einfache Schnittstellen häufig über standardisierte REST-GET-Requests funktionieren, setzen viele moderne Ticketsysteme auf GraphQL-Schnittstellen per POST-Methode mit komplexen URL-Abfragen.

Durch die Verknüpfung von Webhooks, einem spezialisierten KI-Agenten und maßgeschneiderten KI-Aktionen (AI Actions) können Live-Anfragen präzise im KI-Chatbot beantwortet werden. Dies umfasst die automatische Umrechnung von Preisangaben (z. B. Cent in Euro), die Auswertung von Zeitzonen, die Filterung von Gruppengrößen sowie die Abfrage in flexiblen Zeitfenstern.

1. Voraussetzungen und System-Bausteine
2. Webhook anlegen (GraphQL)
3. KI-Agenten konfigurieren
4. Event-Katalog als Wissensquelle verknüpfen
5. KI-Aktion „Verfügbarkeit“ (Tagesabfrage) anlegen
6. KI-Aktion „Nächster Termin“ (weites Zeitfenster) anlegen
7. Instruktionen und Systemregeln definieren
8. Tests im KI-Playground durchführen
9. Veröffentlichung und fortlaufende Wartung
10. Optionales Hintergrundwissen: Warum die Vorgaben so lauten
    

1. Voraussetzungen und System-Bausteine

Für die technische Umsetzung einer Echtzeit-Verfügbarkeitsabfrage werden folgende Komponenten im moinAI Hub erstellt:

• 1x Webhook: Die technische Schnittstelle zum externen Ticketsystem.
• 1x KI-Agent: Die fachliche Zuständigkeit für das Thema „Ticketverfügbarkeit“.
• 1-2x Wissensquellen: Die Webseiten oder Dokumente mit Beschreibungen des Event-Katalogs (im Beispiel die Seiten zu den Führungen des Museums) sowie optional die FAQ-Seite zu Buchungs- und Stornierungsbedingungen.
• 2x KI-Aktionen: Die logischen Verknüpfungen zwischen KI-Agent, Webhook und Regelwerk (eine Aktion für konkrete Tagesabfragen und eine Aktion für die Suche nach dem nächsten freien Termin).
• 1x Instruktionen: Das Regelwerk für das Antwortverhalten des KI-Agenten.

Zusätzliche Rahmenbedingungen:

• Mandantenkennung: Die Domain des Ticketshops (im Beispiel ticket.stadtmuseum-moiniburg.de). Diese wird als Header-Wert bei Webhook-Aufrufen mitgesendet, damit das externe Ticketsystem die Anfrage zuordnen kann.
  
  

Für die in dieser Anleitung beschriebene Lese-Abfrage ist kein API-Schlüssel erforderlich, da die öffentliche Lesesicht des Ticketsystems genutzt wird. Bei geschützten APIs, die eine Schreibberechtigung oder Authentifizierung erfordern, kann ein API-Key oder Bearer-Token im Header hinterlegt werden, wie im Anwendungsbeispiel „Bestellstatus“ des Hauptartikels Webhooks anwenden und konfigurieren gezeigt.

2. Webhook anlegen (GraphQL)

Die technische Anbindung an das Ticketsystem erfolgt über einen zentralen Webhook.

1. Der Zugriff erfolgt im moinAI Hub über den Pfad Integrationen > API-Connectors.
2. Ein Klick auf Webhook erstellen öffnet eine leere Konfigurationsmaske.
3. Die folgenden Feldwerte werden übernommen:

query($d: [DateRange!], $t: [IdOrNumber!], $p: ID!) {
  eventTemplatePotentialEvents(
    posId: $p
    dates: $d
    eventTemplates: $t
    includeQuota: true
    quantity: 1
    first: 100
  ) {
    edges { node {
      spanBeginStr      # Startzeit als Text in Ortszeit -> für Antworten
      name              # Name des Events / der Preisvariante
      remainingQuota    # freie Plätze (0 = ausgebucht)
      maxQuota          # Gesamtkapazität, nur zur Einordnung
      currentPriceValue # aktueller Preis in Cent
      defaultPriceValue # Normalpreis in Cent
    } }
  }
}

{ "p": "auto",
  "d": ["[2026-08-15,2026-08-16)"],   # Tag, Ende exklusiv
  "t": [1001,1002,1003] }             # IDs der Highlight-Führung

Der Webhook sollte direkt nach dem Anlegen einmal über die Testfunktion des Hubs ausgeführt werden. Erwartet wird der Status 200 mit einem data-Block. Eine Antwort mit dem Schlüssel errors bedeutet in der Regel, dass die Ziel-URL nicht vollständig oder nicht unverändert übernommen wurde. Wie das Testen von Webhooks grundsätzlich funktioniert, beschreibt der Abschnitt Testen und Validierung im Hauptartikel.

3. KI-Agenten konfigurieren

Für das Thema „Ticketverfügbarkeit“ wird ein eigener, spezialisierter KI-Agent angelegt. Eine Vermischung mit allgemeinen FAQ-Agenten ist nicht zu empfehlen, da die spezifischen Verhaltensregeln ausschließlich für Verfügbarkeitsfragen gelten sollen.

Die Erstellung eines KI-Agenten ist im Hauptartikel KI-Agenten anlegen ausführlich beschrieben.

1. Die Erstellung erfolgt im Menüpunkt Knowledge Base über das Plus-Symbol.
2. Die Felder werden folgendermaßen definiert:

Die Beschreibung des KI-Agenten dient dem System als Entscheidungsgrundlage, ob eine Anforderung bei diesem Agenten verarbeitet wird. Sie sollte die gängigen Begriffe enthalten, die Nutzer:innen im Chat verwenden, im Beispiel also „Führung“ und „Rallye“ statt der internen Formatbezeichnungen des Ticketsystems.

4. Event-Katalog als Wissensquelle verknüpfen

Der Webhook liefert dynamische Zahlen wie Uhrzeiten, freie Plätze und Preise, enthält jedoch keine redaktionellen Erklärungen zu Event-Inhalten, Dauer oder Zielgruppen. Damit der KI-Agent auch inhaltliche Rückfragen beantworten kann (z. B. „Was ist der Unterschied zwischen der Highlight-Führung und der Taschenlampen-Führung?“), werden ihm in der Knowledge Base passende Wissensquellen zugeordnet:

• Die Übersichtsseite des Event-Katalogs, im Beispiel „Führungen und Termine" (https://stadtmuseum-moiniburg.de/fuehrungen), sowie die Detailseiten aller öffentlich buchbaren Angebote.
• Die FAQ-Seite zu Buchungs- und Stornierungsbedingungen, im Beispiel „Tickets, Buchung und Storno" (https://stadtmuseum-moiniburg.de/service/tickets-faq).

Das Einlesen läuft asynchron: Eine Wissensquelle ist erst nutzbar, sobald sie den Status „trainiert“ erreicht hat.

Gezielte Verlinkungen einzelner Unterseiten liefern präzisere Ergebnisse als das Einlesen der gesamten Webseite, da Navigations- und Footer-Texte die Antwortqualität verwässern können.

5. KI-Aktion „Verfügbarkeit“ (Tagesabfrage) anlegen

Die KI-Aktion verbindet den angelegten Webhook mit dem KI-Agenten. Diese erste Aktion verarbeitet Anfragen, die sich auf ein bestimmtes Datum beziehen (im Beispiel „Habt ihr am Samstag noch Plätze für die Highlight-Führung?“).

Allgemeine Details zu Funktionsweise und Typen finden sich im Artikel KI-Aktionen anlegen.

1. Der Aufruf erfolgt im moinAI Hub über den Pfad Knowledge Base > RAG > Add Action in der Karte Actions & Follow-Up.
2. Unter Tool auswählen wird der Webhook „Verfügbarkeit“ ausgewählt.
3. Die folgenden Konfigurationen werden hinterlegt:

• Aktionsname: Verfügbarkeit
• Toolbeschreibung: Prüft freie Plätze, buchbare Startzeiten und Preise eines Events an EINEM Tag. Nutze das Tool, wenn der Nutzer wissen will, ob ein Event buchbar ist, wie viele Plätze frei sind oder welche Uhrzeiten es gibt. Frage immer genau einen Tag ab: bis = der Tag nach von. Bei Fragen über mehrere Tage prüfe den ersten Tag und biete weitere Tage einzeln an.
• Anweisungen danach: Uhrzeiten nur aus spanBeginStr, nie aus spanBegin (UTC). currentPriceValue.amount ist in Cent: 1200 = 12,00 EUR, durch 100 teilen. remainingQuota ist die Zahl freier Plätze, 0 heißt ausgebucht. Hat der Nutzer eine Personenzahl genannt, nenne nur Termine, deren remainingQuota diese Zahl erreicht oder übersteigt. Ein Termin mit weniger freien Plätzen darf nicht vorkommen, auch nicht als früheste oder späteste Zeit. Reicht kein Termin, sage das und nenne die größte verfügbare Platzzahl. Nenne bis zu fünf Startzeiten konkret, bei mehr die früheste und späteste. Erfinde keine Zwischenzeiten. Ist die Liste leer, wird das Event an diesem Tag nicht angeboten. Antworte dann: "Am [Datum] wird die [Event] nicht angeboten. Soll ich den nächsten Termin für dich suchen?" Verwende nicht "fällt aus", "entfällt" oder "ausgebucht". Enthält die Antwort errors oder kein data, nenne keine Termine und verweise auf die Buchungsseite. Diese Antwort ist abschließend, rufe danach kein weiteres Tool auf.

Parameter für die Tagesabfrage

Über das Plus-Symbol im Abschnitt Parameter werden vier Parameter vom Typ Zeichenfolge angelegt:

Die drei IDs der Highlight-Führung stehen für Vollpreis, ermäßigten Eintritt und Familienticket. Ein Format kann im Ticketsystem also mehrere IDs haben, obwohl Gäste es als ein einziges Angebot wahrnehmen.

Die eigenen IDs stellt der Betreiber des Ticketsystems bereit. Sie gehören zu den Angaben, die in der Übersicht der benötigten Schnittstellen-Angaben aufgeführt sind und gemeinsam beim Anbieter angefragt werden. Die Liste sollte alle Preisvarianten eines Formats enthalten und keine internen oder nicht öffentlich buchbaren Formate.

6. KI-Aktion „Nächster Termin“ (weites Zeitfenster) anlegen

Eine zweite KI-Aktion deckt Fragen ab, bei denen kein festes Datum genannt wird (z. B. „Wann ist die nächste Taschenlampen-Führung?"). Da seltene Events bei einer reinen Tagesabfrage nicht gefunden würden, arbeitet diese Aktion mit einem 90-Tage-Fenster. Die Taschenlampen-Führung findet nur einmal im Monat statt: Eine Abfrage für einen einzelnen Tag geht deshalb in den meisten Fällen leer aus, obwohl es einen nächsten Termin gibt. Die Grenze von 100 Terminen pro Abfrage stört dabei nicht: Die Trefferliste ist chronologisch sortiert, der früheste Termin steht also immer am Anfang, auch wenn das Ende der Liste abgeschnitten wird.

Diese Aktion verwendet denselben Webhook „Verfügbarkeit“.

• Aktionsname: Nächster Termin
• Toolbeschreibung: Findet den NÄCHSTEN stattfindenden Termin eines Events, wenn der Nutzer keinen konkreten Tag nennt: "Wann ist die nächste Taschenlampen-Führung?", "Wann findet das wieder statt?", "Wann kann ich frühestens kommen?". Nutze es NICHT, wenn der Nutzer einen konkreten Tag nennt, dafür ist das Tool Verfügbarkeit zuständig. Nutze pro Antwort nur eines der beiden Tools.
• Anweisungen danach: Die Liste ist chronologisch sortiert. Nenne den frühesten Termin mit Datum und Uhrzeit aus spanBeginStr, dazu bei Bedarf die nächsten ein bis zwei Termine, und die freien Plätze aus remainingQuota. Preis aus currentPriceValue.amount in Cent, durch 100 teilen. Ist die Liste leer, findet die Veranstaltung in den nächsten Monaten nicht statt: sage das und verweise auf die Buchungsseite. Nenne nie Termine, die nicht in der Liste stehen. Diese Antwort ist abschließend, rufe danach kein weiteres Tool auf.

Parameter-Abweichung für das weite Zeitfenster

Auch diese Aktion erhält vier Parameter vom Typ Zeichenfolge, ausdrücklich auch von und bis, obwohl sie ein Datum enthalten. Der Typ Zahl kann das Format YYYY-MM-DD nicht übergeben.

Die Parameter tourtyp und sprache entsprechen der Konfiguration aus der KI-Aktion „Verfügbarkeit“. Bei den Datumsparametern werden die Beschreibungen folgendermaßen angepasst:

7. Instruktionen und Systemregeln definieren

Im moinAI Hub ist eine strikte Aufteilung zwischen allgemeinen Agenten-Regeln (Instruktionen) und aktionsbezogenen Datenverarbeitungen vorgesehen:

• Instruktionen (im KI-Agenten): Globale Verhaltensregeln, Systemrolle und Tonalität.
• Anweisungen danach (in der KI-Aktion): Technische Feldauswertung, Einheitenumrechnung und Fehlerhandling der Schnittstelle.

Der folgende Textblock wird im moinAI Hub über den Pfad Knowledge Base > RAG in der Kachel Instruktionen des Agenten „Ticketverfügbarkeit“ hinterlegt:

Du gibst Auskunft über freie Plätze und Startzeiten der Führungen und Veranstaltungen des Museums. Prüfe erst, antworte dann nur mit den erhaltenen Werten. Erfinde nie Termine, Uhrzeiten, Plätze oder Preise. Prüfe pro Antwort genau einmal. Kündige keine weitere Prüfung an, sondern frage, ob du sie durchführen sollst. Bei Fragen über mehrere Tage einen Tag konkret beantworten und weitere einzeln anbieten, nie von einem Tag auf andere schließen.  Ohne genanntes Event gilt die Highlight-Führung, ohne Datum heute, nenne die Annahme. Antworte in der Sprache des Nutzers. Sprich nie über Technik oder die Datenherkunft.

Weiterführende Sicherheitsrichtlinien und Schutzmechanismen gegen Manipulationen (z. B. Versuche, Systemprompts auszulesen) sind in den Artikeln Guardrails und Schutz vor Prompt Injection detailliert beschrieben.

8. Tests im KI-Playground durchführen

Vor der Freigabe erfolgt die Funktionsprüfung im KI-Playground. Die folgende Testliste dient als Abnahmekriterium:

Testfall 4 prüft zugleich den wichtigsten Sonderfall des Museums: Eine Gruppe, die im Chat nach Plätzen fragt, sucht keine buchbare Gruppenführung, sondern 25 Einzelplätze in einer öffentlichen Führung. Die internen Gruppenformate bleiben außen vor, weil ihre IDs nicht im Parameter tourtyp stehen.

Zahlen aus den Antworten sollten stichprobenartig im echten Ticketshop gegengeprüft werden. Ein Abgleich stellt sicher, dass Parameter und Zeitzonen korrekt verarbeitet werden. Eine flüssig formulierte Antwort mit falschen Zahlen ist der Fehler, der im Betrieb am längsten unentdeckt bleibt.

Zusätzlich sollte bei jedem Test geprüft werden, ob der richtige KI-Agent gewählt wurde. Landet eine Anfrage beim falschen KI-Agenten, wird die Zuordnung über die Feedback-Funktion korrigiert und die Beschreibung des KI-Agenten nachgeschärft.

9. Veröffentlichung und fortlaufende Wartung

Nach erfolgreicher Prüfung im KI-Playground werden die Einstellungen live geschaltet.

Vor der Freischaltung werden zwei Einstellungen geprüft, weil der KI-Chatbot ab diesem Zeitpunkt Preise und Kontingente nennt: Der Antwort-Guard (Schutz gegen Aussagen ohne Wissensgrundlage) sollte aktiv sein, und die Tonalität sollte auf die eigene Marke eingestellt sein.

1. Den KI-Agenten Ticketverfügbarkeit für den gewünschten Kanal (z. B. das Chat-Widget der Webseite) auf Aktiv setzen.
2. Die Veröffentlichung im Hub über die zentrale Veröffentlichung durchführen. Erst nach dieser Bestätigung stehen die KI-Aktionen für echte Unterhaltungen im Chat-Widget zur Verfügung.
3. Nach der Veröffentlichung eine Kontrollfrage im veröffentlichten Chat-Widget stellen.

Regelmäßige Wartung

Termine, Uhrzeiten, freie Plätze und Preise werden nicht gepflegt, sie kommen bei jeder Anfrage frisch aus dem Ticketsystem. Aufmerksamkeit braucht genau eine Stelle:

Sobald im externen Ticketsystem neue Event-Formate angelegt werden, müssen deren IDs im Parameter tourtyp beider KI-Aktionen (Verfügbarkeit und Nächster Termin) nachgetragen werden. Ohne diese IDs bleiben neue Angebote für den KI-Chatbot unsichtbar. Legt das Museum etwa eine Sonderführung zur Wechselausstellung an, bleibt sie im Chat unauffindbar, bis ihre ID in beiden Aktionen steht. Intern genutzte oder private Buchungs-IDs werden bewusst weggelassen, damit diese nicht im öffentlichen Chat angeboten werden, im Beispiel die Schulklassen-Führung, die Kindergarten-Gruppe und die private Sonderöffnung.

Zusätzlich empfiehlt es sich, einmal im Quartal die Testfälle 1, 4 und 5 aus der Abnahmeliste im veröffentlichten Chat-Widget zu wiederholen. So fallen Änderungen an der Schnittstelle auf, bevor sie im Betrieb sichtbar werden.

10. Optionales Hintergrundwissen: Warum die Vorgaben so lauten

Vier Eigenschaften solcher Schnittstellen erklären, warum die Vorgaben in dieser Anleitung so formuliert sind. Bei späteren Anpassungen sollten diese Punkte unberührt bleiben.