Terminbuchung in jeden Voice Bot integrieren — in 10 Minuten

Was du bauen wirst

Am Ende dieses Tutorials kann dein Voice Bot:

1. Prüfen, ob ein Wunschtermin frei ist — in natürlicher Sprache ("nächsten Donnerstag um 15 Uhr")
2. Den Termin auf einem echten Google Calendar buchen
3. Bestehende Termine absagen oder verschieben

Das funktioniert mit jeder Sprachplattform, die externe API-Aufrufe oder MCP unterstützt: Retell, Vapi, Bland, Synthflow oder dein eigenes Setup.

Voraussetzungen

• Ein Google Calendar (den du für Termine nutzt)
• Ein FlowCaptain-Account mit API-Key (sk_live_...)
• Dein Kalender mit dem FlowCaptain-Service-Account geteilt (die E-Mail bekommst du beim Setup)

Kein SDK nötig. Nur HTTP-Requests.

Option A: REST API (funktioniert überall)

Schritt 1: Verfügbarkeit prüfen

Dein Voice Bot nimmt auf, was der Anrufer sagt — "Habt ihr Dienstag um 3 noch was frei?" — und schickt es direkt an FlowCaptain. Kein Date-Parsing auf deiner Seite nötig.

curl -X POST https://api.flowcaptain.ai/api/v1/check-availability \
  -H "Authorization: Bearer sk_live_dein_key_hier" \
  -H "Content-Type: application/json" \
  -d '{"query": "Dienstag um 15 Uhr"}'

Antwort — Termin ist frei:

{
  "action": "confirm",
  "success": true,
  "humanReadable": "Dienstag, 25.02 um 15:00 Uhr ist verfügbar",
  "result": "Zeit ist verfügbar",
  "day": "Dienstag",
  "date": "25.02",
  "time": "15:00"
}

Antwort — Termin belegt, Alternativen verfügbar:

{
  "action": "suggest",
  "success": false,
  "humanReadable": "15:00 Uhr am Dienstag, 25.02 ist leider belegt. Alternativ: 14:00 Uhr oder 16:00 Uhr",
  "result": "angefragter Termin nicht verfügbar aber 2 alternative Zeitfenster verfügbar",
  "day": "Dienstag",
  "date": "25.02",
  "time1": "14:00",
  "time2": "16:00"
}

Das humanReadable-Feld ist ein ganzer Satz, den du direkt an die TTS deines Voice Bots übergeben kannst. Das action-Feld sagt deinem Bot, was als Nächstes passieren soll: confirm (zum Buchen anbieten), suggest (Alternativen nennen), reject (geschlossen/Feiertag) oder clarify (mehrdeutige Eingabe).

Schritt 2: Termin buchen

Sobald der Anrufer eine Zeit bestätigt:

curl -X POST https://api.flowcaptain.ai/api/v1/book-appointment \
  -H "Authorization: Bearer sk_live_dein_key_hier" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "2026-02-25T15:00:00+01:00",
    "callerName": "Max Mustermann",
    "callerIdNumber": "+491761234567",
    "reason": "Beratung"
  }'

Antwort:

{
  "action": "booked",
  "success": true,
  "humanReadable": "Termin bestätigt: Dienstag, 25.02 um 15:00 Uhr",
  "result": "Termin bestätigt",
  "day": "Dienstag",
  "date": "25.02",
  "time": "15:00",
  "appointmentId": "a1b2c3d4-..."
}

Der Termin ist jetzt im Google Calendar. FlowCaptain prüft die Verfügbarkeit nochmal direkt vor der Buchung — Doppelbuchungen sind ausgeschlossen, auch wenn zwei Leute gleichzeitig anrufen.

Zum callerIdNumber-Feld: Wenn deine Sprachplattform die Rufnummer des Anrufers vom Telefonsystem liefert (Retell, Vapi und die meisten Plattformen tun das), übergib sie hier. Die ist 100% korrekt — anders als eine Telefonnummer, die der Anrufer sagt, die durch ASR-Fehler verfälscht sein kann. Das macht Stornierung und Umbuchung zuverlässig.

Schritt 3: Stornieren oder Umbuchen

# Stornieren
curl -X POST https://api.flowcaptain.ai/api/v1/cancel-appointment \
  -H "Authorization: Bearer sk_live_dein_key_hier" \
  -H "Content-Type: application/json" \
  -d '{
    "callerIdNumber": "+491761234567",
    "language": "de"
  }'

# Umbuchen
curl -X POST https://api.flowcaptain.ai/api/v1/reschedule-appointment \
  -H "Authorization: Bearer sk_live_dein_key_hier" \
  -H "Content-Type: application/json" \
  -d '{
    "callerIdNumber": "+491761234567",
    "newDateTime": "2026-02-27T10:00:00+01:00"
  }'

Antwort Stornierung:

{
  "action": "cancelled",
  "success": true,
  "humanReadable": "Termin am Dienstag, 25.02 um 15:00 Uhr wurde storniert"
}

Antwort Umbuchung:

{
  "action": "rescheduled",
  "success": true,
  "humanReadable": "Termin verschoben: Donnerstag, 27.02 um 10:00 Uhr",
  "previousDay": "Dienstag",
  "previousDate": "25.02",
  "previousTime": "15:00"
}

FlowCaptain findet den Termin über die Caller-ID, prüft die neue Zeit gegen Öffnungszeiten und bestehende Buchungen und verschiebt den Google-Calendar-Eintrag. Ist die neue Zeit belegt, werden Alternativen vorgeschlagen.

Retell-Integration

Über Custom Functions

1. Im Retell-Agent: Tools → Add Custom Function
2. Funktion checkAvailability anlegen:
   • URL: https://api.flowcaptain.ai/api/v1/check-availability
   • Methode: POST
   • Header: Authorization: Bearer sk_live_dein_key_hier
   • Parameter: checkAvail (string) — "Die Terminanfrage des Anrufers"

Retell sendet {"args": {"checkAvail": "Dienstag um 15 Uhr"}} — FlowCaptain versteht sowohl dieses Format als auch das direkte {"query": "..."} Format.

Für bookAppointment, cancelAppointment und rescheduleAppointment analog wiederholen.

Über MCP (empfohlen)

Noch einfacher — eine URL, keine Funktions-Konfiguration:

1. Gehe zu Tools → Add MCP
2. URL eingeben: https://api.flowcaptain.ai/mcp
3. Header hinzufügen: Authorization: Bearer sk_live_dein_key_hier
4. Die vier Tools erscheinen automatisch

Dein KI-Agent sieht die Tool-Beschreibungen, versteht wann welches Tool aufgerufen werden soll und steuert den Gesprächsablauf selbstständig.

Andere Plattformen (Vapi, Bland, Synthflow)

Jede Plattform, die HTTP-POST-Requests machen kann, kann die REST API aus Schritt 1-3 nutzen. Unterstützt die Plattform MCPs Streamable HTTP Transport, kann sie sich auch auf https://api.flowcaptain.ai/mcp mit Accept: application/json, text/event-stream verbinden.

Das NLP übernimmt FlowCaptain

Kein Date-Parsing auf deiner Seite nötig. FlowCaptain versteht all das:

• "nächsten Donnerstag nachmittags"
• "tomorrow at 10"
• "irgendwann diese Woche"
• "in 3 Tagen"
• "Freitag"

Deutsch und Englisch werden automatisch erkannt. Die Antwortsprache passt sich der Eingabesprache an.

Zeitraum-Anfragen wie "diese Woche" oder "Montag bis Mittwoch" liefern den ersten freien Slot im Bereich. Konkrete Anfragen wie "Dienstag um 15 Uhr" prüfen genau diesen Slot und bieten Alternativen an, wenn er belegt ist.

Was die API übernimmt

• Öffnungszeiten-Prüfung — bucht nicht außerhalb der Geschäftszeiten
• Feiertags-Erkennung — pro Bundesland
• Alternative Zeitfenster — mit Abstand nach Termindauer verteilt
• Doppelbuchungs-Schutz — prüft den Kalender nochmal direkt vor jeder Buchung
• Zeitzonen — alle Zeiten in der Zeitzone des Betriebs
• Zweisprachig — Deutsch und Englisch, automatisch erkannt

Zusammenfassung

Beide Optionen nutzen dasselbe Backend. Gleiche Verfügbarkeitslogik, gleicher Kalender, gleiche Ergebnisse.

Beide Optionen nutzen dasselbe Backend. Gleiche Verfügbarkeitslogik, gleicher Kalender, gleiche Ergebnisse. Fang einfach mit den curl-Befehlen oben an.