Siirry sisältöön

Oppaat

Yhteydet

Sekä tekoälyavustaja (Claude, ChatGPT) että puhelussa toimiva puheagentti voivat lukea Google Kalenteria ja Apple Calendaria ja hyväksynnän jälkeen muuttaa olemassa olevaa tapahtumaa - ja volain oman moottorin puheagentti voi lisäksi löytää vapaan ajan suoraan puhelun aikana ja varata tapaamisen heti. Applen kohdalla läpinäkymättömät tunnisteet on säilytettävä ennallaan ja toistuvien sarjojen kanssa on oltava varovainen.

Mikä onnistuu ja mikä ei

  • Listaa yhdistetyt kalenterit ja niiden tapahtumat.
  • Muuttaa olemassa olevan tapahtuman nimeä, alkua tai loppua.
  • volain oman moottorin puheagentti löytää vapaan ajan puhelun aikana ja varaa tapaamisen suoraan.
  • Löytää vapaita aikoja ja luo tapaamisen myös puheluiden ulkopuolella REST-rajapinnan ja MCP:n kautta.

Ei onnistu

  • Ei poista yhtään tapahtumaa.
  • Ei etsi vapaita aikoja usean osallistujan väliltä.

Google-tilin yhdistäminen

Google-tili yhdistetään portaalissa osiossa Yhteydet (portaalin englanninkielisessä valikossa kohta on nimeltään "Integrations"). Kun tili on yhdistetty, sama API-avain näkee saman sekä REST-rajapinnan että MCP:n kautta - erillistä kirjautumista ei tarvita.

Tili irrotetaan portaalissa tai REST-kutsulla DELETE /v1/integrations/{id}. REST irrottaa integraation välittömästi ilman erillistä vahvistuskenttää, joten kutsu on tehtävä vasta käyttäjän nimenomaisen hyväksynnän jälkeen. MCP:ssä ei ole irrotustyökalua.

Apple Calendar

Yhdistetään sovelluskohtaisella salasanalla (ei Apple-tilin tavallisella salasanalla) portaalin osiossa Yhteydet ja API. Yhdistäminen onnistuu myös REST-kutsulla POST /v1/integrations sisällöllä {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP ei vastaanota tunnuksia ja käyttää tiliä vasta sen yhdistämisen jälkeen.

list_calendar_events ja REST GET /v1/integrations/{id}/events tukevat Apple Calendaria. Palautettu läpinäkymätön externalId on annettava muuttamattomana arvona eventId kutsulle get_calendar_event ja muutoksissa; se ei ole iCalendar-UID. Rivi, jolla on recurring: true, edustaa koko toistuvaa sarjaa, ja sen muuttaminen muuttaa sarjan perustaa, ei yksittäistä esiintymää; yksittäiset poikkeukset säilyvät.

calendarId:n on oltava jokin list_calendars-kutsun palauttamista osoitteista - kaiken muun API hylkää virheellä 400 calendar_invalid_calendar.

Ajat puhelun aikana

volain oman moottorin puheagentti voi itse puhelun aikana löytää vapaan ajan ja varata tapaamisen suoraan - tämä ei koske chatissa toimivaa tekoälyavustajaa, vaan puhelua, jota puheagentti itse hoitaa. Toiminto otetaan käyttöön agentin editorin Kalenteri-välilehdellä: valitaan yhteys, kalenteri ja saatavuussäännöt (aikaikkunat viikonpäivittäin, tapaamisen pituus, väli tapaamisten välillä, vähimmäisaika etukäteen, hakuhorisontti).

  • Toimii vain volain oman puhemoottorin agentilla - ElevenLabsissa olevalla agentilla asetus tallentuu ja odottaa automaattista moottorin vaihtoa.
  • Agentti ei koskaan kerro, mitä kalenterissa on - vain sen, onko tietty aika vapaa.
  • Soittajan puhelinnumero kirjoitetaan tapahtumaan vain, jos agentti tietää sen; piilotettu numero tuottaa tapahtuman ilman puhelinnumeroa.
  • Sama vapaiden aikojen haku ja tapaamisen varaus toimivat myös puheluiden ulkopuolella REST-rajapinnan (POST .../availability, POST .../events) ja MCP:n (find_free_slots, create_calendar_event) kautta.

Fakturoid ja ABRA Flexi

Tämä sivu käsittelee vain kalentereita. Fakturoid ja ABRA Flexi yhdistetään samassa paikassa (list_integrations/GET /v1/integrations, portaalin osio Yhteydet ja API), mutta laskujen lukemisella ja niiden käytöllä muistutustehtävissä on oma oppaansa Laskut.

Agentin toimintajärjestys

Tapahtuman muuttaminen on aina kuusi vaihetta tässä järjestyksessä:

  • 1. list_integrations - yhdistetyt kalenterit ja niiden integrationId.
  • 2. list_calendars - kyseisen yhteyden kalenterit ja niiden calendarId.
  • 3. list_calendar_events, sen jälkeen get_calendar_event palautetulla externalId-arvolla eventId:nä - lukee tapahtuman ja sen nykyisen sourceRevisionin.
  • 4. propose_calendar_update - valmistelee muutosehdotuksen, ei vielä kirjoita mitään.
  • 5. Käyttäjän hyväksyntä - agentti näyttää alkuperäiset arvot ja ehdotuksen ja jatkaa vasta sen jälkeen.
  • 6. confirm_calendar_update arvolla confirm: true - vasta tämä vaihe kirjoittaa muutoksen Googleen/Appleen.

REST-vastineet: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, sen jälkeen POST /v1/integrations/{id}/events/{eventId}/propose sisällöllä {calendarId, sourceRevision, patch} ja hyväksynnän jälkeen PATCH /v1/integrations/{id}/events/{eventId} samoilla arvoilla ja confirm: true.

Virheet

  • calendar_stale_revision - Tapahtumaa on sillä välin muutettu muualla - lue se uudelleen (get_calendar_event) ja pyydä käyttäjää hyväksymään uusi ehdotus.
  • calendar_oauth_failed - Google hylkäsi kirjautumisen - yhteys on tehtävä uudelleen portaalissa.
  • calendar_unauthorized - Yhteys ei ole enää voimassa (käyttöoikeus peruttu, tunniste vanhentunut) - yhdistä tili uudelleen.
  • calendar_confirmation_required - Kirjoitus ilman confirm: true -arvoa - ehdotus vahvistetaan vasta käyttäjän hyväksynnän jälkeen.
  • calendar_verification_failed - Kirjoitus meni läpi, mutta uusi luku näyttää jotain muuta kuin lähetetyn muutoksen - tarkista tilanne käsin, älä muokkaa uudelleen sokkona.

Täydellinen taulukko kaikista koodeista on osiossa Kalenterit REST API -viitteessä ja osiossa MCP-virheet.

Turvallisuus

REST API ja MCP eivät koskaan palauta Google- tai Apple-tilin käyttöoikeustunnisteita, ja ne tallennetaan salattuina. Applen appPassword lähetetään REST-rajapinnan kautta vain, jos käyttäjä on jo tallentanut sen turvallisesti ympäristömuuttujaan tai itse nimeämäänsä tiedostoon - sitä ei koskaan kysytä keskustelussa eikä toisteta takaisin. Integraatio irrotetaan portaalissa tai REST-kutsulla DELETE /v1/integrations/{id} käyttäjän nimenomaisen hyväksynnän jälkeen; MCP ei tarjoa irrotusta.