Przewodniki

Połączenia

Państwa asystent AI (Claude, ChatGPT) i agent głosowy w trakcie rozmowy potrafią odczytać Kalendarz Google i Apple Calendar oraz po Państwa zatwierdzeniu zmienić istniejące wydarzenie - a agent głosowy na własnym silniku volai dodatkowo sprawdzi w rozmowie wolny termin i od razu wpisze spotkanie. W przypadku Apple trzeba zachować nieprzejrzyste identyfikatory i uważać na serie cykliczne.

Co potrafi, a czego nie

• Wypisuje połączone kalendarze i ich wydarzenia.
• Zmienia nazwę, początek lub koniec istniejącego wydarzenia.
• Agent głosowy na własnym silniku volai sprawdza w rozmowie wolny termin i od razu wpisuje spotkanie.
• Wyszukuje wolne terminy i zakłada spotkanie także poza rozmową przez REST i MCP.

Czego nie potrafi

• Nie usuwa żadnego wydarzenia.
• Nie szuka wolnych terminów wśród wielu uczestników.

Łączenie konta Google

Konto Google łączą Państwo w portalu w sekcji Połączenia (w angielskim menu portalu pozycja „Integrations”). Gdy konto jest połączone, ten sam klucz API widzi to samo przez REST i MCP - bez dodatkowego logowania.

Konto można odłączyć w portalu lub przez REST DELETE /v1/integrations/{id}. REST odłącza integrację natychmiast i bez dodatkowego pola potwierdzenia, dlatego proszę go wywoływać dopiero po wyraźnym zatwierdzeniu przez użytkownika. Narzędzia MCP do odłączania nie ma.

Apple Calendar

Łączy się hasłem do konkretnej aplikacji (a nie zwykłym hasłem do konta Apple) w portalu w sekcji Dane i integracje. Połączenie umożliwia też REST POST /v1/integrations z {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP nie przyjmuje danych logowania i korzysta z konta dopiero po połączeniu.

list_calendar_events i REST GET /v1/integrations/{id}/events obsługują Apple Calendar. Zwrócone nieprzejrzyste externalId proszę przekazywać bez zmian jako eventId do get_calendar_event i edycji; nie jest to UID z iCalendar. Wiersz z recurring: true reprezentuje całą serię cykliczną, a jego edycja zmienia podstawę serii, a nie pojedyncze wystąpienie; poszczególne wyjątki zostają zachowane.

calendarId musi być jednym z adresów zwróconych przez list_calendars - wszystko inne API odrzuci błędem 400 calendar_invalid_calendar.

Terminy w rozmowie

Agent głosowy na własnym silniku volai potrafi w trakcie rozmowy telefonicznej sprawdzić wolny termin i od razu wpisać spotkanie - nie chodzi o asystenta AI w czacie, lecz o rozmowę prowadzoną przez samego agenta głosowego. Włącza się to w edytorze agenta na karcie Kalendarz: wybierają Państwo połączenie, kalendarz i reguły dostępności (okna według dnia tygodnia, długość spotkania, odstęp między terminami, minimalne wyprzedzenie, horyzont wyszukiwania).

• Działa tylko u agenta na własnym silniku głosowym volai - w przypadku agenta na ElevenLabs ustawienie zostaje zapisane i czeka na automatyczne przełączenie silnika.
• Agent nigdy nie mówi, co jest wpisane w kalendarzu - tylko czy dany termin jest wolny.
• Telefon dzwoniącego jest wpisywany do wydarzenia tylko wtedy, gdy agent go zna; ukryty numer oznacza wydarzenie bez telefonu.
• To samo wyszukiwanie wolnych terminów i zapis spotkania działa także poza rozmową przez REST (POST .../availability, POST .../events) i MCP (find_free_slots, create_calendar_event).

Fakturoid i ABRA Flexi

Ta strona dotyczy tylko kalendarzy. Fakturoid i ABRA Flexi łączy się w tym samym miejscu (list_integrations/GET /v1/integrations, sekcja Dane i integracje w portalu), ale odczyt faktur i ich użycie w Zadaniach z przypomnieniami ma własny przewodnik Faktury.

Procedura dla agenta

Edycja wydarzenia ma zawsze sześć kroków, w tej kolejności:

• 1. list_integrations - połączone kalendarze i ich integrationId.
• 2. list_calendars - kalendarze danego połączenia i ich calendarId.
• 3. list_calendar_events, następnie get_calendar_event ze zwróconym externalId jako eventId - wczytuje wydarzenie i jego aktualne sourceRevision.
• 4. propose_calendar_update - przygotowuje propozycję zmiany, na razie niczego nie zapisuje.
• 5. Zatwierdzenie przez użytkownika - agent pokazuje pierwotne wartości i propozycję, dopiero potem kontynuuje.
• 6. confirm_calendar_update z confirm: true - dopiero ten krok zapisuje zmianę w Google/Apple.

Odpowiedniki REST: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, następnie POST /v1/integrations/{id}/events/{eventId}/propose z {calendarId, sourceRevision, patch} i po zatwierdzeniu PATCH /v1/integrations/{id}/events/{eventId} z tymi samymi wartościami i confirm: true.

Błędy

• calendar_stale_revision - W międzyczasie wydarzenie zostało zmienione gdzie indziej - proszę wczytać je ponownie (get_calendar_event) i poprosić użytkownika o zatwierdzenie nowej propozycji.
• calendar_oauth_failed - Google odrzucił logowanie - połączenie trzeba wykonać ponownie w portalu.
• calendar_unauthorized - Połączenie przestało obowiązywać (cofnięty dostęp, wygasły token) - proszę połączyć konto ponownie.
• calendar_confirmation_required - Zapis bez confirm: true - propozycję proszę potwierdzić dopiero po zatwierdzeniu przez użytkownika.
• calendar_verification_failed - Zapis się powiódł, ale świeży odczyt zwrotny nie odpowiada wysłanej zmianie - proszę sprawdzić stan ręcznie, nie edytować ponownie na ślepo.

Pełną tabelę ze wszystkimi kodami znajdą Państwo w sekcji Kalendarze w referencji REST API oraz w błędach MCP.

Bezpieczeństwo

Tokeny dostępu do konta Google ani Apple nigdy nie są zwracane przez REST API ani MCP, a przechowujemy je w postaci zaszyfrowanej. Apple appPassword proszę wysyłać przez REST tylko wtedy, gdy użytkownik zapisał je już bezpiecznie w zmiennej środowiskowej lub w wskazanym przez siebie pliku - nigdy nie prosić o nie w rozmowie ani nie powtarzać go z powrotem. Integrację odłączają Państwo w portalu lub przez REST DELETE /v1/integrations/{id} po wyraźnym zatwierdzeniu przez użytkownika; MCP odłączania nie oferuje.