Anleitungen

Verbindungen

Ihr KI-Assistent (Claude, ChatGPT) und der Sprachagent im Gespräch können Google Kalender und Apple Calendar lesen und nach Ihrer Freigabe einen bestehenden Termin ändern - und der Sprachagent auf dem eigenen volai-Motor erkennt außerdem direkt im Gespräch einen freien Termin und trägt den Besprechungstermin gleich ein. Bei Apple müssen die undurchsichtigen IDs unverändert bleiben, und bei Terminserien ist Vorsicht geboten.

Was möglich ist und was nicht

• Listet die verbundenen Kalender und ihre Termine auf.
• Ändert Titel, Beginn oder Ende eines bestehenden Termins.
• Der Sprachagent auf dem eigenen volai-Motor erkennt im Gespräch einen freien Termin und trägt die Besprechung sofort ein.
• Findet freie Termine und legt eine Besprechung auch außerhalb eines Gesprächs über REST und MCP an.

Nicht möglich

• Löscht keinen Termin.
• Sucht keine freien Termine über mehrere Teilnehmer hinweg.

Google-Konto verbinden

Das Google-Konto verbinden Sie im Portal im Bereich Verbindungen (im englischen Portalmenü der Eintrag „Integrations“). Sobald das Konto verbunden ist, sieht derselbe API-Schlüssel über REST und MCP dasselbe - eine zweite Anmeldung ist nicht nötig.

Das Konto trennen können Sie im Portal oder über REST DELETE /v1/integrations/{id}. REST trennt die Integration sofort und ohne weiteres Bestätigungsfeld, rufen Sie es daher erst nach ausdrücklicher Freigabe durch den Nutzer auf. Ein MCP-Tool zum Trennen gibt es nicht.

Apple Calendar

Die Verbindung erfolgt mit einem App-spezifischen Passwort (nicht mit dem üblichen Passwort des Apple-Kontos) im Portal im Bereich Daten und Integrationen. Verbinden lässt sich auch über REST POST /v1/integrations mit {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP nimmt keine Zugangsdaten entgegen und nutzt das Konto erst nach der Verbindung.

list_calendar_events und REST GET /v1/integrations/{id}/events unterstützen Apple Calendar. Die zurückgegebene undurchsichtige externalId geben Sie unverändert als eventId an get_calendar_event und an Änderungen weiter; es ist nicht die iCalendar-UID. Eine Zeile mit recurring: true steht für die gesamte Terminserie, und ihre Änderung ändert die Grundlage der Serie, nicht einen einzelnen Termin; einzelne Ausnahmen bleiben erhalten.

calendarId muss eine der Adressen sein, die list_calendars zurückgibt - alles andere lehnt die API mit dem Fehler 400 calendar_invalid_calendar ab.

Termine im Gespräch

Der Sprachagent auf dem eigenen volai-Motor kann direkt im Telefonat einen freien Termin erkennen und die Besprechung gleich eintragen - es geht nicht um einen KI-Assistenten im Chat, sondern um ein Gespräch, das der Sprachagent selbst führt. Eingeschaltet wird das im Editor des Agenten auf der Registerkarte Kalender: Sie wählen die Verbindung, den Kalender und die Verfügbarkeitsregeln (Zeitfenster je Wochentag, Dauer der Besprechung, Puffer zwischen Terminen, Mindestvorlauf, Suchhorizont).

• Funktioniert nur bei einem Agenten auf dem eigenen volai-Sprachmotor - bei einem Agenten auf ElevenLabs wird die Einstellung gespeichert und wartet auf die automatische Umstellung des Motors.
• Der Agent verrät nie, was im Kalender eingetragen ist - nur, ob die angefragte Zeit frei ist.
• Die Telefonnummer des Anrufers wird nur dann in den Termin eingetragen, wenn der Agent sie kennt; eine unterdrückte Nummer bedeutet einen Termin ohne Telefon.
• Dieselbe Suche nach freien Terminen und das Eintragen einer Besprechung funktionieren auch außerhalb eines Gesprächs über REST (POST .../availability, POST .../events) und MCP (find_free_slots, create_calendar_event).

Fakturoid und ABRA Flexi

Diese Seite behandelt nur Kalender. Fakturoid und ABRA Flexi werden an derselben Stelle verbunden (list_integrations/GET /v1/integrations, Bereich Daten und Integrationen im Portal), aber das Lesen von Rechnungen und ihre Verwendung in Aufgaben für Zahlungserinnerungen hat eine eigene Anleitung: Rechnungen.

Vorgehen für den Agenten

Die Änderung eines Termins hat immer sechs Schritte, in dieser Reihenfolge:

• 1. list_integrations - verbundene Kalender und ihre integrationId.
• 2. list_calendars - Kalender der jeweiligen Verbindung und ihre calendarId.
• 3. list_calendar_events, danach get_calendar_event mit der zurückgegebenen externalId als eventId - lädt den Termin und seine aktuelle sourceRevision.
• 4. propose_calendar_update - bereitet einen Änderungsvorschlag vor, schreibt noch nichts.
• 5. Freigabe durch den Nutzer - der Agent zeigt die ursprünglichen Werte und den Vorschlag, erst dann geht er weiter.
• 6. confirm_calendar_update mit confirm: true - erst dieser Schritt schreibt die Änderung zu Google/Apple.

REST-Entsprechungen: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, danach POST /v1/integrations/{id}/events/{eventId}/propose mit {calendarId, sourceRevision, patch} und nach der Freigabe PATCH /v1/integrations/{id}/events/{eventId} mit denselben Werten und confirm: true.

Fehler

• calendar_stale_revision - Der Termin wurde inzwischen anderswo geändert - laden Sie ihn erneut (get_calendar_event) und lassen Sie den Nutzer den neuen Vorschlag freigeben.
• calendar_oauth_failed - Google hat die Anmeldung abgelehnt - die Verbindung muss im Portal erneut hergestellt werden.
• calendar_unauthorized - Die Verbindung ist nicht mehr gültig (widerrufener Zugriff, abgelaufenes Token) - verbinden Sie das Konto erneut.
• calendar_confirmation_required - Schreibvorgang ohne confirm: true - bestätigen Sie den Vorschlag erst nach der Freigabe durch den Nutzer.
• calendar_verification_failed - Der Schreibvorgang lief durch, aber das frische Zurücklesen entspricht nicht der gesendeten Änderung - prüfen Sie den Zustand manuell und ändern Sie nicht blind erneut.

Die vollständige Tabelle mit allen Codes finden Sie im Abschnitt Kalender in der REST-API-Referenz und in den MCP-Fehlern.

Sicherheit

Zugriffstoken für Google- oder Apple-Konten geben weder REST API noch MCP jemals zurück, und wir speichern sie verschlüsselt. Senden Sie das Apple-appPassword über REST nur, wenn der Nutzer es bereits sicher in einer Umgebungsvariablen oder einer von ihm benannten Datei abgelegt hat - fragen Sie nie im Gespräch danach und geben Sie es nicht zurück. Die Integration trennen Sie im Portal oder über REST DELETE /v1/integrations/{id} nach ausdrücklicher Freigabe durch den Nutzer; MCP bietet kein Trennen an.