Buchung mit Cal.com

Kalender verbinden#

Öffnen Sie Agent → Aktionen → Cal.com. Geben Sie einen Cal.com-API-Schlüssel ein, der mit cal_ beginnt, die positive numerische Termintyp-ID und eine IANA-Zeitzone wie Asia/Seoul. Wählen Sie Verbindung speichern. Jeder Agent hat seine eigene Verbindung. Der Schlüssel wird auf dem Server verschlüsselt; das Dashboard zeigt nur die letzten vier Zeichen an. Lassen Sie das Schlüsselfeld beim Aktualisieren einer bestehenden Verbindung leer, um den vorhandenen Schlüssel beizubehalten.

Wählen Sie Verbindung testen, um mit den eingegebenen Einstellungen bis zu drei bevorstehende Zeitfenster der nächsten sieben Tage abzurufen. Dieser Test speichert die Verbindung nicht und erstellt keine Buchung. Keine Zeitfenster können einfach bedeuten, dass der Termintyp in diesem Zeitraum keine Verfügbarkeit hat. Wenn der Test fehlschlägt, prüfen Sie in Cal.com den Schlüssel, den Termintyp und den Zeitplan. Wenn Sie die Verbindung entfernen, werden keine neuen Cal.com-Buchungen mehr vorgenommen; bestehende Buchungen werden dadurch nicht storniert.

Zahlungen werden nicht unterstützt. Google Calendar ist eine separate Option, die noch nicht allgemein verfügbar ist.

Vom Zeitfenster zur Buchung#

1. Der Agent ruft find_slots auf, um die tatsächliche zukünftige Verfügbarkeit abzufragen. Er zeigt bis zu acht Zeiten in der konfigurierten Zeitzone an. Der Standardzeitraum reicht von heute bis sieben Tage später; die maximale Zeitspanne beträgt 14 Tage. Steht nur eine einzige Zeit zur Verfügung, wird sie allein angezeigt.
2. Der Kunde wählt eine Zeit und gibt Name, E-Mail-Adresse und optional eine Notiz an. Der Agent prüft erneut, ob die Zeit frei ist und ob sie in dieser Konversation angeboten wurde. Angebote für Zeitfenster laufen nach 15 Minuten ab.
3. Eine Bestätigungskarte zeigt Datum, Uhrzeit, Zeitzone und die Angaben zum Teilnehmer. Der Kunde muss auf Bestätigen tippen. Eine Chatnachricht oder die bloße Auswahl einer Zeit bucht noch nichts. Der Vorschlag läuft nach 15 Minuten ab und reserviert das Zeitfenster nicht.
4. Erst nach der Bestätigung fordert der Adapter die Cal.com-Buchung an. Das Ergebnis accepted von Cal.com wird zu done, wobei die Buchungs-UID als Referenz dient. pending oder awaiting_host bleibt ausstehend; bei Ablehnung oder Stornierung wird die Buchung als fehlgeschlagen markiert.

Buchungsvorschläge sind in Messaging-Kanälen nur im privaten Chat möglich. Die Probe ruft Cal.com nicht auf und erstellt keine Buchung. Ohne Cal.com-Verbindung bleibt der bestehende Ablauf für Buchungsanfragen verfügbar; er belegt jedoch keine Kalenderreservierung. Wenn Sie Schlüssel, Termintyp oder Zeitzone ändern, wird das Ausführungsziel eines Vorschlags ungültig. Beginnen Sie daher nach Änderungen an der Verbindung von vorn.

Wenn ein Zeitfenster vergeben ist oder das Ergebnis unklar ist#

Ein anderer Kunde kann sich ein Zeitfenster sichern, bevor die Bestätigung abgeschlossen ist. Wenn die Zeit nicht mehr frei ist, meldet der Agent, dass sie nicht verfügbar ist; lehnt Cal.com die Buchung bei der Erstellung ab, zeigt der Beleg einen Fehlschlag an. Bitten Sie um neue Zeiten und bestätigen Sie einen neuen Vorschlag. Der Beleg über den Fehlschlag fügt nicht automatisch neue Auswahlmöglichkeiten hinzu.

Eine Zeitüberschreitung im Netzwerk ist weder ein Beweis für einen Fehlschlag noch für einen Erfolg. Der Beleg zeigt ein unbekanntes Ergebnis an, während der Dienst erneut prüft. Der Create-Endpunkt von Cal.com hat keinen dokumentierten Vertrag für Idempotenzschlüssel. Deshalb speichert der Adapter die Run-ID in metadata.maf_run und sucht über alle Status und Seiten hinweg nach dieser Buchung, bevor er die Erstellung erneut versucht. Eine unvollständige Suche erlaubt niemals eine weitere Create-Anfrage. Das verringert das Risiko von Duplikaten, ist aber keine vom Anbieter gestützte Exactly-once-Garantie. Prüfen Sie nach ausgeschöpften Wiederholungsversuchen Cal.com, bevor Sie eine weitere Buchung vornehmen.

Die Freigabe durch den Host in Cal.com ist von der Freigabe durch den Owner bei benutzerdefinierten Änderungsaktionen zu unterscheiden. Eine ausstehende Cal.com-Buchung wird von dieser Integration nicht automatisch aktualisiert; prüfen Sie ihren endgültigen Status in Cal.com. Das Web-Widget kann den gespeicherten Beleg des Durchlaufs abfragen, und unterstützte private Kanäle erhalten verzögerte Belege im Rahmen ihrer Servicefenster. Siehe Zustellung von Belegen.

API-Versionen und Release-Prüfungen#

Der Adapter sendet Bearer-Authentifizierung und die folgenden endpunktspezifischen cal-api-version-Werte, die am 13.10.2026 anhand der offiziellen Dokumentation überprüft wurden:

Testen Sie vor dem Einsatz mit Kunden eine kontrollierte Buchung, prüfen Sie die UID in Cal.com, probieren Sie ein vergebenes Zeitfenster aus und kontrollieren Sie die Belege in jedem vorgesehenen Kanal. Ein erfolgreicher Verbindungstest belegt nur das Lesen von Zeitfenstern, nicht eine echte Buchung oder die Produktionsreife.