Průvodci

Připojení

Tvůj AI asistent (Claude, ChatGPT) i hlasový agent v hovoru umí přečíst Google Kalendář i Apple Calendar a po tvém schválení upravit existující událost - a hlasový agent na vlastním motoru volai navíc přímo v hovoru zjistí volný termín a schůzku rovnou zapíše. U Apple je potřeba zachovat neprůhledná ID a dát pozor na opakované série.

Co to umí a neumí

• Vypíše připojené kalendáře a jejich události.
• Upraví název, začátek nebo konec existující události.
• Hlasový agent na vlastním motoru volai zjistí v hovoru volný termín a rovnou zapíše schůzku.
• Najde volné termíny a založí schůzku i mimo hovor přes REST a MCP.

Neumí

• Nesmaže žádnou událost.
• Nehledá volné termíny mezi více účastníky.

Připojení Google účtu

Google účet připojíš v portálu v sekci Připojení (v anglickém menu portálu položka „Integrations“). Jakmile je účet připojený, stejný API klíč přes REST i MCP vidí totéž - žádné druhé přihlášení navíc.

Odpojit účet můžeš v portálu nebo přes REST DELETE /v1/integrations/{id}. REST odpojí integraci okamžitě a bez dalšího potvrzovacího pole, proto ho volej až po výslovném schválení uživatelem. MCP nástroj pro odpojení nemá.

Apple Calendar

Připojuje se heslem pro konkrétní aplikaci (ne běžným heslem k Apple účtu) v portálu v sekci Data a integrace. Připojení umí i REST POST /v1/integrations s {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP přihlašovací údaje nepřijímá a účet používá až po připojení.

list_calendar_events i REST GET /v1/integrations/{id}/events podporují Apple Calendar. Vrácené neprůhledné externalId předávej beze změny jako eventId do get_calendar_event a úprav; není to iCalendar UID. Řádek s recurring: true představuje celou opakovanou sérii a její úprava změní základ série, ne jeden výskyt; jednotlivé výjimky zůstanou zachované.

calendarId musí být jedna z adres, které vrátí list_calendars - cokoli jiného API odmítne chybou 400 calendar_invalid_calendar.

Termíny v hovoru

Hlasový agent na vlastním motoru volai umí přímo v telefonátu zjistit volný termín a schůzku rovnou zapsat - nejde o AI asistenta v chatu, ale o hovor, který vede sám hlasový agent. Zapíná se v editoru agenta na záložce Kalendář: vybereš připojení, kalendář a pravidla dostupnosti (okna podle dne v týdnu, délka schůzky, rezerva mezi termíny, minimální předstih, horizont hledání).

• Funguje jen u agenta na vlastním hlasovém motoru volai - u agenta na ElevenLabs se nastavení uloží a čeká na automatické přepnutí motoru.
• Agent nikdy neřekne, co je v kalendáři zapsané - jen jestli je daný čas volný.
• Telefon volajícího se do události zapíše, jen když ho agent zná; skryté číslo znamená událost bez telefonu.
• Totéž hledání volných termínů i zápis schůzky jde i mimo hovor přes REST (POST .../availability, POST .../events) a MCP (find_free_slots, create_calendar_event).

Fakturoid a ABRA Flexi

Tahle stránka pokrývá jen kalendáře. Fakturoid a ABRA Flexi se připojují na stejném místě (list_integrations/GET /v1/integrations, sekce Data a integrace v portálu), ale čtení faktur a jejich použití v upomínkových Úkolech má vlastní průvodce Faktury.

Postup pro agenta

Úprava události má vždy šest kroků, v tomto pořadí:

• 1. list_integrations - připojené kalendáře a jejich integrationId.
• 2. list_calendars - kalendáře daného připojení a jejich calendarId.
• 3. list_calendar_events, potom get_calendar_event s vráceným externalId jako eventId - načte událost a její aktuální sourceRevision.
• 4. propose_calendar_update - připraví návrh změny, zatím nic nezapisuje.
• 5. Schválení uživatelem - agent ukáže původní hodnoty a návrh, teprve pak pokračuje.
• 6. confirm_calendar_update s confirm: true - teprve tenhle krok zapíše změnu ke Google/Apple.

REST ekvivalenty: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, potom POST /v1/integrations/{id}/events/{eventId}/propose s {calendarId, sourceRevision, patch} a po schválení PATCH /v1/integrations/{id}/events/{eventId} se stejnými hodnotami a confirm: true.

Chyby

• calendar_stale_revision - Mezitím se událost změnila jinde - načti ji znovu (get_calendar_event) a nech uživatele schválit nový návrh.
• calendar_oauth_failed - Google odmítl přihlášení - připojení je potřeba udělat znovu v portálu.
• calendar_unauthorized - Připojení přestalo platit (odvolaný přístup, vypršelý token) - připoj účet znovu.
• calendar_confirmation_required - Zápis bez confirm: true - potvrď návrh teprve po schválení uživatelem.
• calendar_verification_failed - Zápis proběhl, ale čerstvé načtení zpět neodpovídá odeslané změně - ověř stav ručně, needituj naslepo znovu.

Úplnou tabulku se všemi kódy najdeš v sekci Kalendáře v REST API referenci a v chybách MCP.

Zabezpečení

Přístupové tokeny k Google ani Apple účtu REST API ani MCP nikdy nevrací a ukládáme je šifrovaně. Apple appPassword pošli přes REST jen tehdy, když ho uživatel už bezpečně uložil do proměnné prostředí nebo jím pojmenovaného souboru - nikdy si o něj neříkej v konverzaci a neopakuj ho zpátky. Integraci odpojíš v portálu nebo přes REST DELETE /v1/integrations/{id} po výslovném schválení uživatelem; MCP odpojení nenabízí.