Verfügbarkeit prüfen

API-Referenz für die Prüfung verfügbarer Terminzeitfenster mit natürlichsprachlichen Anfragen.

Verfügbare Terminzeitfenster mit einer natürlichsprachlichen Anfrage prüfen.

Endpunkt

POST /api/v1/check-availability

Anfrage-Body

{
  "calendarId": "YOUR_CALENDAR_ID",
  "query": "nächsten Montag um 10 Uhr"
}

Feld	Typ	Erforderlich	Beschreibung
calendarId	string	Ja	Deine Kalender-ID — legt fest, welchen Kalender die Anfrage betrifft
query	string	Ja*	Natürlichsprachliche Verfügbarkeitsanfrage auf Deutsch oder Englisch (max. 500 Zeichen)
requestedDateTime	string	Ja*	Alternativ zu `query`: gewünschte Zeit als ISO-8601-Zeitstempel
serviceName	string	Nein	Gewünschte Leistung — deren Dauer bestimmt die Slot-Berechnung
serviceNames	string[]	Nein	Mehrere gewünschte Leistungen (max. 10, Dauern werden addiert)
language	string	Nein	`"de"` oder `"en"` (Standard: `"de"`) — Antwortsprache bei `requestedDateTime`

* Sende entweder query oder requestedDateTime. Fehlen beide, antwortet die API mit 400.

calendarId ist bei jeder Anfrage erforderlich. Du findest sie vorausgefüllt unter Kalender › Name › API im Abschnitt Integrations-Anleitung. Sende sie als Feld im JSON-Body. Falls deine Plattform den Body in einen Umschlag einpackt (z.B. Retells args-Objekt), übergib sie stattdessen als URL-Query-Parameter — ?calendarId=YOUR_CALENDAR_ID — denn die API liest calendarId nur aus dem Top-Level-Body, der Query-Zeichenkette oder den Routen-Parametern, niemals aus einem verschachtelten args-Objekt.

Antwort — Zeit verfügbar

{
  "action": "confirm",
  "success": true,
  "humanReadable": "Montag, 02.03 um 10:00 Uhr ist verfügbar",
  "result": "Zeit ist verfügbar",
  "day": "Montag",
  "date": "02.03",
  "time": "10:00"
}

date hat das Format TT.MM, time das Format HH:mm.

Antwort — Alternativen vorschlagen

Wenn die gewünschte Zeit belegt ist, schlägt FlowCaptain alternative Zeitfenster vor:

{
  "action": "suggest",
  "success": false,
  "humanReadable": "10:00 Uhr am Montag, 02.03 ist leider belegt. Alternativ: 11:00 Uhr, 14:00 Uhr oder 15:00 Uhr",
  "result": "angefragter Termin nicht verfügbar aber 3 alternative Zeitfenster verfügbar",
  "day": "Montag",
  "date": "02.03",
  "time1": "11:00",
  "time2": "14:00",
  "time3": "15:00"
}

Eine einzelne Alternative kommt als time zurück; mehrere als time1, time2, time3. Wie viele Alternativen genannt werden, steuerst du über Max. Vorschläge im Tab Termine & Kalender deines Assistenten.

Antwort — Keine Verfügbarkeit

Wenn der Tag ausgebucht oder geschlossen ist (z.B. Ruhetag oder Feiertag), erklärt humanReadable den Grund:

{
  "action": "reject",
  "success": false,
  "humanReadable": "Freitag, 25.12 ist Feiertag",
  "result": "Feiertag",
  "day": "Freitag",
  "date": "25.12",
  "time": "10:00"
}

Antwort — Rückfrage

Mit action: "clarify" meldet die API, dass etwas fehlt oder unklar ist — zum Beispiel wenn die Anfrage nicht verstanden wurde, ein Wochentag diese oder nächste Woche meinen kann, die Leistung nicht gefunden wurde oder der Kalender eine Leistungsauswahl verlangt. humanReadable enthält die passende Rückfrage, die dein Voice Bot vorlesen kann.

Natürlichsprachliche Beispiele

Das Feld query akzeptiert Freitext auf Deutsch oder Englisch:

"nächsten Montag"
"morgen um 14 Uhr"
"next week Tuesday"
"tomorrow afternoon"
"Haben Sie am Freitag noch etwas frei?"
"Do you have anything on Friday?"

Hinweise

humanReadable ist zum direkten Vorlesen durch deinen Voice Bot gedacht
Bei query antwortet die API in der Sprache, in der die Anfrage formuliert ist; bei requestedDateTime bestimmt language die Sprache
Alternative Vorschläge berücksichtigen Termindauer, Taktung, Pufferzeit und Mindestvorlaufzeit
Wenn Google Kalender vorübergehend nicht erreichbar ist, antwortet die API mit action: "clarify" und einem entsprechenden Hinweis, anstatt anzunehmen, dass der Kalender frei ist