Guider

Anslutningar

Både AI-assistenten (Claude, ChatGPT) och röstagenten i ett samtal kan läsa Google Kalender och Apple Calendar och, efter godkännande, ändra en befintlig händelse - och röstagenten på volais egen motor kan dessutom hitta en ledig tid direkt under samtalet och boka mötet på stört. För Apple gäller det att behålla de ogenomskinliga ID:na och vara försiktig med återkommande serier.

Vad som går och inte går

• Listar anslutna kalendrar och deras händelser.
• Ändrar namn, start eller slut på en befintlig händelse.
• Röstagenten på volais egen motor hittar en ledig tid under samtalet och bokar mötet direkt.
• Hittar lediga tider och skapar ett möte även utanför samtal via REST och MCP.

Går inte

• Tar inte bort någon händelse.
• Söker inte lediga tider mellan flera deltagare.

Ansluta ett Google-konto

Google-kontot ansluts i portalen under avsnittet Anslutningar (i portalens engelska meny heter posten "Integrations"). När kontot är anslutet ser samma API-nyckel samma sak via både REST och MCP - ingen extra inloggning behövs.

Kontot kopplas bort i portalen eller via REST DELETE /v1/integrations/{id}. REST kopplar bort integrationen omedelbart och utan något extra bekräftelsefält, så anropet bör göras först efter uttryckligt godkännande från användaren. MCP har inget verktyg för bortkoppling.

Apple Calendar

Ansluts med ett applikationsspecifikt lösenord (inte det vanliga lösenordet till Apple-kontot) i portalen under avsnittet Data och integrationer. Anslutning går också via REST POST /v1/integrations med {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP tar inte emot inloggningsuppgifter och använder kontot först efter att det anslutits.

list_calendar_events och REST GET /v1/integrations/{id}/events stöder Apple Calendar. Det returnerade ogenomskinliga externalId ska lämnas oförändrat som eventId till get_calendar_event och vid ändringar; det är inte ett iCalendar-UID. En rad med recurring: true representerar hela den återkommande serien och en ändring av den ändrar seriens grund, inte en enskild förekomst; enskilda undantag bevaras.

calendarId måste vara en av adresserna som list_calendars returnerar - allt annat avvisas av API:t med felet 400 calendar_invalid_calendar.

Tider under samtalet

Röstagenten på volais egen motor kan under själva telefonsamtalet hitta en ledig tid och boka mötet direkt - det gäller inte AI-assistenten i en chatt, utan ett samtal som röstagenten för själv. Funktionen slås på i agentens editor under fliken Kalender: anslutning, kalender och tillgänglighetsregler väljs (fönster per veckodag, mötets längd, marginal mellan tider, minsta framförhållning, sökhorisont).

• Fungerar bara för en agent på volais egen röstmotor - för en agent på ElevenLabs sparas inställningen och väntar på det automatiska bytet av motor.
• Agenten säger aldrig vad som står i kalendern - bara om en viss tid är ledig.
• Uppringarens telefonnummer skrivs in i händelsen bara om agenten känner till det; ett dolt nummer ger en händelse utan telefonnummer.
• Samma sökning efter lediga tider och bokning av möte går även utanför samtal via REST (POST .../availability, POST .../events) och MCP (find_free_slots, create_calendar_event).

Fakturoid och ABRA Flexi

Den här sidan täcker bara kalendrar. Fakturoid och ABRA Flexi ansluts på samma ställe (list_integrations/GET /v1/integrations, avsnittet Data och integrationer i portalen), men läsningen av fakturor och deras användning i påminnelseuppgifter har en egen guide Fakturor.

Arbetsgång för agenten

En ändring av en händelse har alltid sex steg, i den här ordningen:

• 1. list_integrations - anslutna kalendrar och deras integrationId.
• 2. list_calendars - kalendrarna för den aktuella anslutningen och deras calendarId.
• 3. list_calendar_events, därefter get_calendar_event med det returnerade externalId som eventId - läser in händelsen och dess aktuella sourceRevision.
• 4. propose_calendar_update - förbereder ett ändringsförslag, skriver ännu ingenting.
• 5. Godkännande av användaren - agenten visar de ursprungliga värdena och förslaget och fortsätter först därefter.
• 6. confirm_calendar_update med confirm: true - först det här steget skriver ändringen till Google/Apple.

REST-motsvarigheter: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, därefter POST /v1/integrations/{id}/events/{eventId}/propose med {calendarId, sourceRevision, patch} och efter godkännande PATCH /v1/integrations/{id}/events/{eventId} med samma värden och confirm: true.

Fel

• calendar_stale_revision - Händelsen har under tiden ändrats på annat håll - läs in den på nytt (get_calendar_event) och låt användaren godkänna ett nytt förslag.
• calendar_oauth_failed - Google avvisade inloggningen - anslutningen måste göras om i portalen.
• calendar_unauthorized - Anslutningen gäller inte längre (återkallad åtkomst, utgången token) - anslut kontot på nytt.
• calendar_confirmation_required - Skrivning utan confirm: true - bekräfta förslaget först efter användarens godkännande.
• calendar_verification_failed - Skrivningen gick igenom, men en ny läsning visar något annat än den skickade ändringen - kontrollera läget manuellt, redigera inte på nytt i blindo.

Den fullständiga tabellen med alla koder finns i avsnittet Kalendrar i REST-API-referensen och i MCP-fel.

Säkerhet

Åtkomsttoken till Google- eller Apple-kontot returneras aldrig av REST-API:t eller MCP och lagras krypterade. Apple appPassword ska skickas via REST bara om användaren redan har sparat det säkert i en miljövariabel eller en fil som användaren själv har namngett - be aldrig om det i konversationen och upprepa det aldrig tillbaka. Integrationen kopplas bort i portalen eller via REST DELETE /v1/integrations/{id} efter användarens uttryckliga godkännande; MCP erbjuder ingen bortkoppling.