Verfügbarkeit prüfen

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

Verfügbarkeit prüfen

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 Nachmittag"
}

Feld	Typ	Erforderlich	Beschreibung
calendarId	string	Ja	Deine Kalender-ID — legt fest, welchen Kalender die Anfrage betrifft
query	string	Ja	Natürlichsprachliche Verfügbarkeitsanfrage (Deutsch oder Englisch)
requestedDateTime	string	Nein	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
language	string	Nein	`"de"` oder `"en"` (Standard: `"de"`) — Sprache der Antwort

calendarId ist bei jeder Anfrage erforderlich. Du findest sie vorausgefüllt unter Dashboard → Kalender → API → 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, der 3. März um 10:00 Uhr ist verfügbar.",
  "day": "Montag",
  "date": "2026-03-03",
  "time": "10:00"
}

Antwort — Alternativen vorschlagen

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

{
  "action": "suggest",
  "humanReadable": "Um 10:00 Uhr ist leider schon belegt. Am Montag wären noch 11:00, 14:00 oder 15:00 Uhr frei.",
  "day": "Montag",
  "date": "2026-03-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 in den Assistenten-Einstellungen.

Antwort — Keine Verfügbarkeit

Wenn der Tag ausgebucht oder geschlossen ist (auch an Feiertagen und während Ruhezeiten), erklärt humanReadable den Grund:

{
  "action": "reject",
  "humanReadable": "Am Montag, 3. Oktober, haben wir wegen des Tags der Deutschen Einheit geschlossen."
}

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
Die Antwortsprache steuert der language-Parameter
Alternative Vorschläge berücksichtigen Termindauer, Taktung, Pufferzeit und Mindestvorlaufzeit
Wenn Google Kalender vorübergehend nicht erreichbar ist, gibt die API einen Fehler zurück, anstatt anzunehmen, dass der Kalender frei ist