📅 Configurazione Google Calendar

Guida completa per integrare Google Calendar con AI4CALL: crea appuntamenti automatici, verifica disponibilità slot, gestisci calendario aziendale direttamente durante le chiamate

AI4CALL - MCP Configurazione Google Calendar

Vai in "MARKET""Marketplace Plugin" e clicca su Acquista di "Google Calendar"FREE

Vai in "MARKET""I Miei Plugin" e clicca su Configura di "Google Calendar"

⚠️ Servizi di terze parti

Le integrazioni descritte fanno riferimento a servizi di terze parti.
Rate limit, modalità di autenticazione, configurazioni tecniche, costi e policy sono definiti esclusivamente dai rispettivi provider e possono variare nel tempo.

I costi dei servizi esterni sono sostenuti direttamente dall’utente finale a favore dei fornitori dei servizi stessi e non sono in alcun modo gestiti o intermediati dal nostro portale (es. Meta o altri fornitori per WhatsApp, Zapier, Calendly, ecc.).

1

📖 Cos'è Google Calendar integration e come funziona

Google Calendar integration consente all'assistente AI4CALL di interagire direttamente con calendari Google: creare appuntamenti, verificare disponibilità, eliminare eventi, tutto durante la chiamata.

📅 operazioni Google Calendar disponibili:
1. Creazione eventi (calendar_create):
→ crea nuovo appuntamento su Google Calendar
→ specifica: titolo, data/ora inizio/fine, location, partecipanti
→ Google invia inviti email automatici a partecipanti
→ evento appare immediatamente in Google Calendar web/app/mobile

2. Verifica disponibilità (calendar_check_availability):
→ controlla se slot temporale è libero o occupato
→ query range date: "dal 15 al 20 marzo, ore 9-18"
→ restituisce: busy (occupato) o free (libero) per ogni slot
→ usa per proporre orari disponibili al cliente

3. Lista eventi (calendar_list):
→ recupera eventi esistenti in range temporale
→ filtra per: date, titolo, location, partecipanti
→ usa per: riepilogo appuntamenti, ricerca evento specifico

4. Creazione condizionale (calendar_create_if_free):
→ crea evento SOLO se slot libero
→ evita sovrapposizioni automaticamente
→ se occupato: restituisce errore, AI propone slot alternativi

5. Eliminazione eventi (calendar_delete):
→ cancella appuntamento esistente
→ Google invia email cancellazione a partecipanti
→ evento rimosso da tutti calendari
💡 Come AI4CALL usa Google Calendar
Workflow tipico prenotazione appuntamento:

[Cliente chiama agenzia/studio]

[Assistente AI4CALL risponde]

[Cliente: "Vorrei prenotare appuntamento"]

[AI chiede: "Che giorno preferisce?"]

[Cliente: "Martedì prossimo mattina"]

[AI invoca: calendar_check_availability]

[Range: martedì 9:00-13:00, intervalli 30 min]

[Google Calendar restituisce: 10:00 FREE, 10:30 BUSY, 11:00 FREE...]

[AI: "Disponibile martedì alle 10:00 o 11:00"]

[Cliente: "10:00 va bene"]

[AI invoca: calendar_create_if_free]

[Google crea evento, invia invito email cliente]

[AI conferma: "Appuntamento confermato martedì 15 marzo ore 10:00"]

[AI (opzionale): invia conferma WhatsApp/SMS]

Vantaggio: cliente prenota appuntamento istantaneamente via telefono senza attendere operatore umano o accedere a booking web.
⚠️ Limitazioni Google Calendar integration
Cosa Google Calendar integration NON può fare:
  • ❌ NO modifica eventi esistenti (devi eliminare + ricreare)
  • ❌ NO eventi ricorrenti nativi (devi creare serie manualmente)
  • ❌ NO gestione automatica buffer time tra appuntamenti (implementa in prompt)
  • ❌ NO limiti max appuntamenti/giorno automatici (implementa logica custom)
  • ❌ NO round-robin team assignment automatico (usa Calendly per questo)

Workaround: queste limitazioni si superano con prompt engineering intelligente. Esempio buffer time: istruisci AI a cercare slot con +15min prima/dopo occupato.
2

🔐 Autorizza account Google tramite OAuth

Per permettere ad AI4CALL di accedere a Google Calendar, devi autorizzare account Google tramite procedura OAuth sicura.

🔐 procedura completa autorizzazione OAuth:
  1. Seleziona "Google Calendar" dall'elenco dei tuoi Plugin:
    → vedi banner rosso: "Nessuna email Google autorizzata"
  2. Aggiungi email Google da autorizzare:
    • Campo "Partecipanti": inserisci email account Google (es. agenzia@gmail.com)
    • Clicca pulsante "+" (più)
    • Email appare sotto con badge grigio + pulsante "AUTH"
  3. Avvia autorizzazione OAuth:
    • Clicca "AUTH" accanto email
    • Banner arancione appare: "Alcune email necessitano autorizzazione OAuth"
    • Sistema invia email a indirizzo specificato
    • Oggetto email: tipo "Autorizza AI4CALL per Google Calendar"
  4. Completa autorizzazione (lato utente):
    • Apri email ricevuta (controlla spam se non arriva)
    • Clicca link autorizzazione nell'email
    • Si apre popup/pagina Google OAuth
    • Seleziona account Google da autorizzare
    • Google mostra permessi richiesti: "Gestisci il tuo calendario Google"
    • Clicca "Consenti" o "Allow"
    • Pagina conferma: "Autorizzazione completata"
  5. Verifica autorizzazione (torna ad AI4CALL):
    • Pannello AI4CALL: clicca "VERIFICA"
    • Sistema controlla se Google ha confermato autorizzazione
    • Se OK: email diventa VERDE con ✅
    • Banner verde: "Email Google disponibili per il calendario: [email]"
  6. Clicca "SALVA TOOL" per finalizzare
  7. ✅ Autorizzazione completata - tool Google Calendar ora funzionanti!
Email autorizzata con successo!
Quando email diventa verde nel pannello:
  • ✅ AI4CALL ha accesso completo Google Calendar
  • ✅ può creare/leggere/eliminare eventi
  • ✅ autorizzazione permanente (fino a revoca manuale)
  • ✅ tool disponibili per uso assistente

Importante: autorizzazione vale per account Google specifico. Per gestire calendari multipli (team): autorizza account owner calendari condivisi.
🔍 Troubleshooting autorizzazione fallita
Email non arriva:
  • → controlla cartella spam/posta indesiderata
  • → verifica email Google corretta (no typo)
  • → attendi 5-10 minuti (delay invio email)
  • → riprova: rimuovi email + ri-aggiungi + AUTH

Popup OAuth non si apre:
  • → browser blocca popup - abilita popup per AI4CALL
  • → click destro link email → "Apri in nuova scheda"

Google nega autorizzazione:
  • → account Google Workspace: admin deve autorizzare app terze
  • → 2FA problematico: completa verifica 2 fattori
  • → verifica account Google non sospeso/limitato

VERIFICA fallisce (email resta grigia):
  • → autorizzazione OAuth non completata - ripeti click link email
  • → attendi 30 secondi dopo "Allow" Google, poi VERIFICA
  • → link email scaduto (>24h) - richiedi nuovo AUTH
Google Calendar OAuth Flow
Flusso autorizzazione OAuth: (1) inserisci email, (2) clicca AUTH, (3) completa autorizzazione Google, (4) email diventa verde
3

👥 Aggiungi email partecipanti autorizzati

Configura quali account Google possono essere usati dall'assistente per gestire calendari.

👥 gestione email partecipanti:
Scopo sezione "Partecipanti":
→ lista account Google autorizzati a operare su calendari
→ ogni email = un account Google con calendari accessibili
→ AI4CALL può usare SOLO email presenti e autorizzate (verdi)

Casi d'uso tipici:

1. Singolo calendario aziendale:
→ aggiungi 1 email: agenzia@gmail.com
→ tutti appuntamenti su calendario primario questo account
→ setup più semplice - raccomandato per inizio

2. Calendari multipli team:
→ aggiungi email team members: medico1@clinic.com, medico2@clinic.com
→ AI può creare appuntamenti su calendario specifico medico
→ istruisci prompt: "se cliente chiede Dr. Rossi, usa medico1@clinic.com"

3. Calendari condivisi Google Workspace:
→ aggiungi email owner calendario condiviso: booking@azienda.com
→ account ha accesso a calendari team@..., sala-riunioni@... etc.
→ specifica calendarId in tool per selezionare quale calendario

Aggiunta email:
  1. Campo "email@domain.com": inserisci indirizzo Gmail o Google Workspace
  2. Clicca "+" (più) → email appare sotto in lista grigio
  3. Clicca "AUTH" → segui procedura OAuth (step 2)
  4. Dopo autorizzazione: email diventa verde ✅
  5. Ripeti per ogni account Google da autorizzare

Rimozione email:
→ clicca icona cestino accanto email
→ conferma rimozione
→ autorizzazione revocata, tool non possono più usare questo account
💡 Best practice gestione email
Setup raccomandato per agenzie/studi:

OPZIONE A - Calendario centralizzato (semplice):
→ crea account Google dedicato: booking@tuaagenzia.com
→ usa calendario primario per tutti appuntamenti
→ condividi calendario con team (Google Calendar sharing)
→ autorizza solo questo account in AI4CALL
✅ pro: gestione semplice, un solo account
⚠️ contro: tutti eventi su stesso calendario

OPZIONE B - Calendari individuali team (flessibile):
→ ogni membro team ha account Google personale
→ autorizza tutti account in AI4CALL
→ istruisci AI a selezionare calendario giusto basato su richiesta
→ esempio: "appuntamento con Dr. Rossi" → usa medico1@clinic.com
✅ pro: calendari separati, flessibilità massima
⚠️ contro: gestione multipla, più complesso

Scelta dipende da: dimensione team, tipo business, complessità scheduling richiesta
Email partecipanti configurate
Nella sezione "Partecipanti" dovresti vedere:
  • ✅ email account Google aggiunte
  • ✅ badge VERDE per email autorizzate
  • ✅ banner verde: "Email Google disponibili per il calendario"
  • ✅ pulsante "SALVA TOOL" abilitato

Ora puoi procedere con selezione tool calendario da abilitare!
4

🛠️ Seleziona tool Google Calendar da abilitare

Scegli quali operazioni calendario rendere disponibili all'assistente tramite checkbox "Plugin configurati".

🛠️ 5 tool Google Calendar disponibili:
1. calendar_create ☑️
→ crea un nuovo evento nel calendario Google
→ parametri: email, calendarId, summary, description, startTime, endTime, location, attendees
→ crea SEMPRE evento anche se slot occupato (possibili sovrapposizioni)
usa per: eventi multi-partecipante, meeting flessibili, appuntamenti dove overlap OK

2. calendar_list ☑️
→ lista eventi dal calendario Google
→ parametri: email, calendarId, timeMin, timeMax, maxResults, search (filtra per titolo/descrizione/location)
→ restituisce: array eventi con tutti dettagli (id, titolo, data, partecipanti, etc.)
usa per: riepilogo appuntamenti cliente, ricerca evento specifico, lista settimana

3. calendar_check_availability ☑️
→ verifica disponibilità di uno slot temporale
→ parametri: email, calendarId, startTime, endTime
→ restituisce: busy (occupato) o free (libero)
usa per: trovare slot disponibili prima di proporre al cliente
raccomandazione: SEMPRE abilitato - fondamentale per evitare conflitti

4. calendar_create_if_free ☑️
→ crea evento solo se lo slot è libero
→ parametri: identici a calendar_create
→ workflow: (1) check availability interno, (2) se free: crea, (3) se busy: errore
usa per: appuntamenti esclusivi (medico, parrucchiere, consulenze 1-to-1)
raccomandazione: PREFERISCI questo vs calendar_create per evitare doppie prenotazioni

5. calendar_delete ☑️
→ elimina un evento dal calendario
→ parametri: email, calendarId, eventId
→ Google invia email cancellazione a tutti partecipanti
usa per: cancellazioni appuntamenti su richiesta cliente
attenzione: azione irreversibile - istruisci AI a chiedere conferma
💡 Configurazioni consigliate tool
Setup COMPLETO (raccomandato produzione):
✅ calendar_create
✅ calendar_list
✅ calendar_check_availability
✅ calendar_create_if_free
✅ calendar_delete
→ assistente autonomo completo: crea, consulta, cancella intelligentemente

Setup BOOKING ONLY (solo prenotazioni):
❌ calendar_create (disabilitato per sicurezza)
✅ calendar_list
✅ calendar_check_availability
✅ calendar_create_if_free (UNICO tool creazione abilitato)
❌ calendar_delete (richiede operatore umano)
→ solo prenotazioni sicure senza rischio conflitti/cancellazioni accidentali

Setup READ-ONLY (solo consultazione):
❌ calendar_create
✅ calendar_list
✅ calendar_check_availability
❌ calendar_create_if_free
❌ calendar_delete
→ assistente fornisce solo info appuntamenti, no modifiche calendario
⚙️ Quando usare calendar_create vs calendar_create_if_free
Regola decisione:

Usa calendar_create_if_free quando:
  • ✅ appuntamenti 1-to-1 esclusivi (medico, consulente, parrucchiere)
  • ✅ slot non sovrapponibili (risorsa singola: sala, tecnico, etc.)
  • ✅ cliente si aspetta conferma immediata o proposta alternativa
  • ✅ business penalizzato da doppie prenotazioni

Usa calendar_create quando:
  • ✅ eventi multi-partecipante (meeting, riunioni team)
  • ✅ reminder personali (non conflitti)
  • ✅ eventi informativi (webinar, eventi pubblici)
  • ✅ vuoi flessibilità massima (accetti sovrapposizioni controllate)

Best practice: per 99% use case booking clienti, usa calendar_create_if_free. Disabilita calendar_create se possibile per sicurezza.
Google Calendar Tools Selection
Pannello "Plugin configurati": checkbox per abilitare/disabilitare i 5 tool Google Calendar
5

🤖 Istruisci l'assistente per workflow Google Calendar

Configura il prompt dell'assistente per utilizzare correttamente i tool Google Calendar e gestire prenotazioni intelligentemente.

📝 Workflow consigliati da inserire nel prompt
1. Prenotazione appuntamento con verifica disponibilità:
"Quando cliente chiede appuntamento: (1) chiedi preferenza giorno/orario, (2) usa calendar_check_availability per range (es. mattina = 9-13), (3) identifica primi 2-3 slot liberi, (4) proponi: 'Disponibile martedì 10:00, 11:00 o mercoledì 9:30', (5) cliente sceglie, (6) calendar_create_if_free, (7) se successo: conferma verbale + invia WhatsApp/Email con dettagli, (8) se slot occupato nel frattempo: proponi slot successivo disponibile."

2. Riepilogo appuntamenti cliente:
"Se cliente chiede 'quali appuntamenti ho?': (1) calendar_list da oggi a +30 giorni, (2) filtra eventi con email/nome cliente in attendees, (3) elenca cronologicamente: 'Ha 3 appuntamenti: martedì 15 ore 10, giovedì 20 ore 15, lunedì 25 ore 11'. Se nessun appuntamento: 'Non ho appuntamenti registrati per lei'. NO menzionare eventi altri clienti (privacy)."

3. Cancellazione appuntamento sicura:
"Per cancellazione: (1) calendar_list per trovare evento, (2) conferma con cliente: 'Vuole cancellare appuntamento [giorno] ore [ora]?', (3) se conferma: calendar_delete(eventId), (4) conferma cancellazione: 'Appuntamento cancellato, riceverà email conferma da Google', (5) opzionale: notifica operatore via Telegram. SEMPRE chiedi conferma prima di delete - azione irreversibile."

4. Gestione slot occupato (fallback intelligente):
"Se calendar_create_if_free fallisce (slot occupato): (1) 'Mi dispiace, quello slot è già prenotato', (2) calendar_check_availability range +/- 2 ore, (3) proponi alternative: 'Disponibile 1 ora dopo alle [ora] o domani stesso orario', (4) NO comunicare cliente precedente - privacy. Continua finché cliente trova slot OK o rinuncia."
🧪 Test workflow completo
Test 1 - Prenotazione slot libero:
  1. Chiama assistente: "Vorrei prenotare appuntamento"
  2. Segui conversazione fornendo: giorno (es. "domani"), orario (es. "mattina"), nome, email
  3. Verifica AI propone slot disponibili (check_availability)
  4. Scegli slot, verifica creazione (create_if_free)
  5. Controlla Google Calendar web: evento appare correttamente
  6. Verifica ricezione email invito Google

Test 2 - Slot occupato (fallback):
  1. Crea evento manualmente su Google Calendar (es. domani 10:00)
  2. Chiama AI chiedendo appuntamento "domani ore 10"
  3. Verifica AI rileva slot occupato
  4. Verifica propone alternative automaticamente

Test 3 - Cancellazione:
  1. Dopo test 1, chiama: "Devo cancellare appuntamento"
  2. Verifica AI trova evento corretto (calendar_list)
  3. Conferma cancellazione
  4. Controlla Google Calendar: evento eliminato
  5. Verifica email cancellazione da Google

❓ Domande frequenti

Risposte alle domande più comuni su Google Calendar integration

Procedura OAuth: (1) pannello AI4CALL → Google Calendar Tool → Partecipanti, (2) inserisci email Google account (es. agenzia@gmail.com), (3) clicca "+", (4) clicca "AUTH" accanto email, (5) sistema invia email con link autorizzazione, (6) apri email, clicca link, (7) popup Google OAuth: seleziona account, (8) accetta permessi "Gestisci calendario", (9) torna ad AI4CALL, clicca "VERIFICA", (10) email diventa verde = autorizzato. Autorizzazione una tantum - valida fino a revoca.

calendar_create: crea evento SEMPRE, anche se slot già occupato → può generare sovrapposizioni/conflitti. Usa per: eventi multi-partecipante, appuntamenti flessibili. calendar_create_if_free: verifica PRIMA disponibilità slot → crea SOLO se libero, altrimenti errore. Usa per: appuntamenti esclusivi (medico, parrucchiere) dove sovrapposizioni inaccettabili. Workflow calendar_create_if_free: (1) check_availability, (2) se free: crea evento, (3) se busy: proponi slot alternativi.

Google Calendar usa formato ISO 8601 con timezone. Esempi: "2025-03-15T10:00:00+01:00" (CET Italia), "2025-03-15T10:00:00Z" (UTC). Parametri startTime/endTime richiedono timezone esplicito. Best practice: (1) usa timezone locale business (Europe/Rome per Italia), (2) AI4CALL converte automaticamente orari locali cliente → ISO 8601, (3) Google Calendar mostra eventi nel fuso orario utente automaticamente. Evita confusione: specifica sempre timezone in prompt ("ore 10:00 CET").

Sì. Parametro "attendees" in calendar_create accetta array email: ["cliente@email.com", "medico@clinic.com"]. Google invia automaticamente invito email con: link "Aggiungi al calendario", dettagli evento, opzioni Accetta/Rifiuta/Forse. Partecipanti ricevono notifiche modifiche/cancellazioni. Privacy: usa solo se hai consenso partecipanti. Alternativa: crea evento senza attendees, invia conferma manuale via Email SMTP tool.

Sì. Parametro "calendarId" specifica quale calendario usare. Opzioni: (1) "primary" (default): calendario principale account Google, (2) calendarId specifico (es. "team@group.calendar.google.com"): calendario condiviso/secondario. Per usare calendari multipli: (1) autorizza account Google owner calendari, (2) trova calendarId: Google Calendar web → Settings → calendario → Calendar ID, (3) specifica in tool: calendar_create(calendarId="team@...", ...). Account deve avere permessi write su calendario.

Dipende da tool usato. calendar_create: crea evento COMUNQUE → sovrapposizione/conflitto visibile in calendario (eventi sovrapposti). calendar_create_if_free: (1) verifica prima con calendar_check_availability, (2) se busy: restituisce errore "slot non disponibile", (3) AI deve gestire: proporre orari alternativi. Istruisci prompt: "se slot occupato, cerca prossimi 3 slot liberi e proponi al cliente". Evita conflitti: usa SEMPRE calendar_create_if_free per appuntamenti esclusivi.

Privacy dipende da: (1) calendario usato: "primary" = privato owner account, "shared calendar" = visibile membri team, (2) visibilità evento: "private" (default) = solo owner/attendees, "public" = tutti con link calendario. Eventi AI4CALL: default private, visibili solo account Google autorizzato + attendees invitati. Per condividere con team: (1) usa calendario condiviso Google (team@...), (2) tutti membri vedono eventi, oppure (3) invita team via attendees parameter.

Tool calendar_delete(email, calendarId, eventId). Workflow: (1) cliente chiama chiedendo cancellazione, (2) AI usa calendar_list per trovare evento (cerca per summary/data), (3) identifica eventId corretto, (4) calendar_delete(eventId=...), (5) Google elimina evento, (6) se aveva attendees: Google invia email cancellazione automatica.

Non esiste un tool calendar_update. In caso di modifica, l’assistente gestisce automaticamente l’operazione cancellando l’evento esistente e creandone uno nuovo con i dati aggiornati. I partecipanti ricevono una cancellazione e una nuovo invito.

Tool calendar_check_availability verifica disponibilità range temporale. Workflow intelligente: (1) cliente chiede "appuntamento questa settimana", (2) AI definisce range (es. oggi → +7 giorni, lun-ven 9-18), (3) loop: check_availability ogni ora/slot, (4) identifica primi 3-5 slot free, (5) propone al cliente: "disponibile martedì 10:00, mercoledì 14:00, giovedì 11:00", (6) cliente sceglie, (7) calendar_create_if_free. Efficiente: cerca solo working hours, evita weekend/festivi automaticamente.

Calendario personale (primary): privato singolo utente, eventi visibili solo a lui + attendees invitati. Calendario condiviso (team@group.calendar.google.com): condiviso gruppo utenti Google Workspace, tutti membri vedono eventi. Per AI4CALL team: (1) crea calendario Google condiviso "AI4CALL Appuntamenti", (2) aggiungi membri team come editor, (3) usa calendarId condiviso in tool, (4) tutti vedono appuntamenti creati da AI. Vantaggio: centralizzazione, backup umano se AI fallisce.

Troubleshooting: (1) verifica email Google valida e accessibile, (2) controlla spam per email autorizzazione, (3) click link autorizzazione entro 24h (scade), (4) browser: abilita popup (OAuth apre popup), (5) account Google: verifica non ha 2FA bloccante o policy admin restrittive, (6) Google Cloud: verifica OAuth consent screen approvato (se app production), (7) retry: pannello AI4CALL → rimuovi email → ri-aggiungi → AUTH. Errore persistente: contatta supporto AI4CALL.

Formato obbligatorio: ISO 8601 con timezone. Esempi validi: "2025-03-15T10:00:00+01:00" (CET), "2025-03-15T09:00:00Z" (UTC), "2025-03-15T10:00:00" (floating - sconsigliato). Componenti: YYYY-MM-DDTHH:MM:SS+TZ. AI4CALL converte automaticamente da linguaggio naturale: "domani ore 10" → ISO 8601 corretto. Errore comune: dimenticare timezone → evento appare orario sbagliato. Best practice: istruisci AI a confermare sempre orario verbalmente: "confermo appuntamento martedì 15 marzo ore 10:00".

Workflow sicuro anti-conflitti: (1) usa SEMPRE calendar_create_if_free (non calendar_create) per appuntamenti esclusivi, (2) verifica disponibilità PRIMA di confermare al cliente: "momento, verifico disponibilità...", (3) se slot occupato: proponi alternativi automaticamente, (4) dopo creazione: conferma verbale "appuntamento confermato martedì 15 ore 10", (5) invia conferma scritta multi-channel (email + WhatsApp), (6) calendario condiviso team: tutti vedono occupazioni real-time. Evita race conditions: calendario singolo centralizzato, non calendari multipli disconnessi.


Alcuni degli utilizzatori di ai4call