Ghiduri

Conexiuni

Asistentul dumneavoastră AI (Claude, ChatGPT) și agentul vocal din timpul apelului pot citi Google Calendar și Apple Calendar și, cu aprobarea dumneavoastră, pot modifica un eveniment existent - iar agentul vocal de pe motorul propriu volai află direct în apel un termen liber și înscrie imediat întâlnirea. La Apple trebuie păstrate ID-urile opace și trebuie să aveți grijă la seriile recurente.

Ce poate și ce nu poate face

• Afișează calendarele conectate și evenimentele lor.
• Modifică titlul, începutul sau sfârșitul unui eveniment existent.
• Agentul vocal de pe motorul propriu volai află în apel un termen liber și înscrie imediat întâlnirea.
• Găsește termene libere și creează o întâlnire și în afara apelului, prin REST și MCP.

Ce nu poate face

• Nu șterge niciun eveniment.
• Nu caută termene libere între mai mulți participanți.

Conectarea contului Google

Contul Google îl conectați în portal, în secțiunea Conexiuni (în meniul portalului în engleză, elementul „Integrations”). După ce contul este conectat, aceeași cheie API vede același lucru atât prin REST, cât și prin MCP - fără o a doua autentificare.

Contul îl puteți deconecta în portal sau prin REST DELETE /v1/integrations/{id}. REST deconectează integrarea imediat și fără un câmp de confirmare suplimentar, de aceea apelați-l abia după aprobarea explicită a utilizatorului. MCP nu are un instrument de deconectare.

Apple Calendar

Se conectează cu o parolă pentru o anumită aplicație (nu cu parola obișnuită a contului Apple), în portal, în secțiunea Date și integrări. Conectarea o poate face și REST POST /v1/integrations cu {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP nu acceptă date de autentificare și folosește contul abia după conectare.

list_calendar_events și REST GET /v1/integrations/{id}/events acceptă Apple Calendar. externalId-ul opac returnat transmiteți-l neschimbat ca eventId în get_calendar_event și la modificări; nu este un UID iCalendar. Un rând cu recurring: true reprezintă întreaga serie recurentă, iar modificarea lui schimbă baza seriei, nu o singură apariție; excepțiile individuale se păstrează.

calendarId trebuie să fie una dintre adresele returnate de list_calendars - orice altceva este respins de API cu eroarea 400 calendar_invalid_calendar.

Termene în apel

Agentul vocal de pe motorul propriu volai poate afla direct în convorbire un termen liber și poate înscrie imediat întâlnirea - nu este vorba despre un asistent AI din chat, ci despre un apel purtat chiar de agentul vocal. Se activează în editorul agentului, în fila Calendar: alegeți conexiunea, calendarul și regulile de disponibilitate (intervale pe zilele săptămânii, durata întâlnirii, rezerva dintre termene, preavizul minim, orizontul de căutare).

• Funcționează doar la agentul de pe motorul vocal propriu volai - la un agent pe ElevenLabs setarea se salvează și așteaptă comutarea automată a motorului.
• Agentul nu spune niciodată ce este înscris în calendar - doar dacă ora respectivă este liberă.
• Telefonul apelantului se înscrie în eveniment doar dacă agentul îl cunoaște; un număr ascuns înseamnă un eveniment fără telefon.
• Aceeași căutare de termene libere și înscrierea întâlnirii merg și în afara apelului, prin REST (POST .../availability, POST .../events) și MCP (find_free_slots, create_calendar_event).

Fakturoid și ABRA Flexi

Această pagină acoperă doar calendarele. Fakturoid și ABRA Flexi se conectează în același loc (list_integrations/GET /v1/integrations, secțiunea Date și integrări din portal), dar citirea facturilor și folosirea lor în sarcinile de reamintire au un ghid propriu Facturi.

Procedura pentru agent

Modificarea unui eveniment are întotdeauna șase pași, în această ordine:

• 1. list_integrations - calendarele conectate și integrationId-ul lor.
• 2. list_calendars - calendarele conexiunii respective și calendarId-ul lor.
• 3. list_calendar_events, apoi get_calendar_event cu externalId-ul returnat ca eventId - încarcă evenimentul și sourceRevision-ul său actual.
• 4. propose_calendar_update - pregătește propunerea de modificare, deocamdată nu scrie nimic.
• 5. Aprobarea utilizatorului - agentul arată valorile inițiale și propunerea, abia apoi continuă.
• 6. confirm_calendar_update cu confirm: true - abia acest pas scrie modificarea la Google/Apple.

Echivalente REST: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, apoi POST /v1/integrations/{id}/events/{eventId}/propose cu {calendarId, sourceRevision, patch} și, după aprobare, PATCH /v1/integrations/{id}/events/{eventId} cu aceleași valori și confirm: true.

Erori

• calendar_stale_revision - Între timp evenimentul a fost modificat în altă parte - încărcați-l din nou (get_calendar_event) și lăsați utilizatorul să aprobe o propunere nouă.
• calendar_oauth_failed - Google a respins autentificarea - conexiunea trebuie refăcută în portal.
• calendar_unauthorized - Conexiunea nu mai este valabilă (acces revocat, token expirat) - conectați din nou contul.
• calendar_confirmation_required - Scriere fără confirm: true - confirmați propunerea abia după aprobarea utilizatorului.
• calendar_verification_failed - Scrierea s-a făcut, dar citirea proaspătă ulterioară nu corespunde modificării trimise - verificați starea manual, nu editați din nou orbește.

Tabelul complet cu toate codurile îl găsiți în secțiunea Calendare din referința API REST și în erorile MCP.

Securitate

Tokenurile de acces la contul Google sau Apple nu sunt returnate niciodată de API-ul REST sau de MCP și sunt stocate criptat. appPassword Apple trimiteți-l prin REST doar dacă utilizatorul l-a salvat deja în siguranță într-o variabilă de mediu sau într-un fișier indicat de el - nu cereți niciodată parola în conversație și nu o repetați înapoi. Integrarea o deconectați în portal sau prin REST DELETE /v1/integrations/{id}, după aprobarea explicită a utilizatorului; MCP nu oferă deconectarea.