Handleidingen

Koppelingen

Uw AI-assistent (Claude, ChatGPT) en de spraakagent in een gesprek kunnen Google Agenda en Apple Calendar lezen en, na uw goedkeuring, een bestaande afspraak wijzigen - en de spraakagent op de eigen engine van volai ziet bovendien tijdens het gesprek zelf of een tijdstip vrij is en legt de afspraak meteen vast. Bij Apple moet u de ondoorzichtige ID's ongewijzigd laten en oppassen met terugkerende reeksen.

Wat het wel en niet kan

• Toont de gekoppelde agenda's en hun afspraken.
• Wijzigt de titel, het begin of het einde van een bestaande afspraak.
• De spraakagent op de eigen engine van volai ziet tijdens het gesprek of een tijdstip vrij is en legt de afspraak meteen vast.
• Zoekt vrije tijdstippen en maakt een afspraak ook buiten een gesprek via REST en MCP.

Kan niet

• Verwijdert nooit een afspraak.
• Zoekt geen vrije tijdstippen voor meerdere deelnemers.

Een Google-account koppelen

Een Google-account koppelt u in het portaal onder Koppelingen (in het Engelstalige portaalmenu het item "Integrations"). Zodra het account is gekoppeld, ziet dezelfde API-sleutel via REST en MCP hetzelfde - een tweede aanmelding is niet nodig.

Een account ontkoppelt u in het portaal of via REST DELETE /v1/integrations/{id}. REST ontkoppelt de integratie onmiddellijk en zonder extra bevestigingsveld, roep het daarom pas aan na uitdrukkelijke goedkeuring door de gebruiker. MCP heeft geen tool om te ontkoppelen.

Apple Calendar

Wordt gekoppeld met een appspecifiek wachtwoord (niet met het gewone wachtwoord van uw Apple-account) in het portaal onder Gegevens en integraties. Koppelen kan ook via REST met POST /v1/integrations en {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP accepteert geen inloggegevens en gebruikt het account pas nadat het is gekoppeld.

list_calendar_events en REST GET /v1/integrations/{id}/events ondersteunen Apple Calendar. Geef de teruggegeven ondoorzichtige externalId ongewijzigd door als eventId aan get_calendar_event en bij wijzigingen; het is geen iCalendar-UID. Een rij met recurring: true is de hele terugkerende reeks en een wijziging past de basis van de reeks aan, niet één voorkomen; afzonderlijke uitzonderingen blijven behouden.

calendarId moet een van de adressen zijn die list_calendars teruggeeft - alles anders wijst de API af met fout 400 calendar_invalid_calendar.

Afspraken tijdens het gesprek

Een spraakagent op de eigen engine van volai kan tijdens het telefoongesprek zelf zien of een tijdstip vrij is en de afspraak meteen vastleggen - het gaat dus niet om een AI-assistent in een chat, maar om een gesprek dat de spraakagent zelf voert. Het schakelt u in bij de agent-editor op het tabblad Agenda: u kiest de koppeling, de agenda en de beschikbaarheidsregels (tijdvensters per weekdag, duur van de afspraak, marge tussen afspraken, minimale voorlooptijd, zoekhorizon).

• Werkt alleen bij een agent op de eigen spraakengine van volai - bij een agent op ElevenLabs wordt de instelling opgeslagen en wacht ze op de automatische overschakeling van de engine.
• De agent zegt nooit wat er in de agenda staat - alleen of een bepaald tijdstip vrij is.
• Het telefoonnummer van de beller wordt alleen in de afspraak vastgelegd als de agent het kent; een verborgen nummer betekent een afspraak zonder telefoonnummer.
• Hetzelfde zoeken naar vrije tijdstippen en het vastleggen van een afspraak kan ook buiten een gesprek via REST (POST .../availability, POST .../events) en MCP (find_free_slots, create_calendar_event).

Fakturoid en ABRA Flexi

Deze pagina behandelt alleen agenda's. Fakturoid en ABRA Flexi koppelt u op dezelfde plek (list_integrations/GET /v1/integrations, het onderdeel Gegevens en integraties in het portaal), maar het lezen van facturen en het gebruik ervan in herinneringstaken heeft een eigen handleiding Facturen.

Werkwijze voor een agent

Het wijzigen van een afspraak bestaat altijd uit zes stappen, in deze volgorde:

• 1. list_integrations - gekoppelde agenda's en hun integrationId.
• 2. list_calendars - de agenda's van die koppeling en hun calendarId.
• 3. list_calendar_events, daarna get_calendar_event met de teruggegeven externalId als eventId - leest de afspraak en de actuele sourceRevision.
• 4. propose_calendar_update - bereidt een voorstel voor, schrijft nog niets weg.
• 5. Goedkeuring door de gebruiker - de agent toont de oorspronkelijke waarden en het voorstel en gaat pas daarna verder.
• 6. confirm_calendar_update met confirm: true - pas deze stap schrijft de wijziging naar Google/Apple.

REST-equivalenten: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, daarna POST /v1/integrations/{id}/events/{eventId}/propose met {calendarId, sourceRevision, patch} en na goedkeuring PATCH /v1/integrations/{id}/events/{eventId} met dezelfde waarden en confirm: true.

Fouten

• calendar_stale_revision - De afspraak is intussen elders gewijzigd - lees haar opnieuw (get_calendar_event) en laat de gebruiker het nieuwe voorstel goedkeuren.
• calendar_oauth_failed - Google heeft de aanmelding geweigerd - de koppeling moet opnieuw in het portaal worden gemaakt.
• calendar_unauthorized - De koppeling is niet meer geldig (toegang ingetrokken, token verlopen) - koppel het account opnieuw.
• calendar_confirmation_required - Schrijfactie zonder confirm: true - bevestig het voorstel pas nadat de gebruiker het heeft goedgekeurd.
• calendar_verification_failed - De schrijfactie is gelukt, maar het verse teruglezen komt niet overeen met de verzonden wijziging - controleer de status handmatig en pas niet blindelings opnieuw aan.

De volledige tabel met alle codes vindt u in het onderdeel Agenda's in de REST API-referentie en in de MCP-fouten.

Beveiliging

Toegangstokens voor een Google- of Apple-account geven REST API en MCP nooit terug en we slaan ze versleuteld op. Stuur een Apple appPassword alleen via REST als de gebruiker het al veilig heeft opgeslagen in een omgevingsvariabele of een door hem benoemd bestand - vraag er nooit om in het gesprek en herhaal het niet. Een integratie ontkoppelt u in het portaal of via REST DELETE /v1/integrations/{id} na uitdrukkelijke goedkeuring door de gebruiker; MCP biedt geen ontkoppeling.