Blocco Firebase - Firestore e Cloud Messaging nel tuo chatbot

Panoramica

Il Blocco Firebase connette il tuo chatbot ChatMaxima direttamente a un progetto Firebase. Permette al tuo flusso di leggere e scrivere documenti in Cloud Firestore e di inviare notifiche push FCM agli utenti della tua app mobile o web, tutto da un unico blocco. Qualsiasi operazione tu configuri viene eseguita nel punto esatto della conversazione in cui posizioni il blocco, così che il tuo bot possa estrarre dati da Firestore, memorizzare lo stato al suo interno o attivare una notifica push in risposta a uno specifico stato della conversazione.

I casi d'uso tipici includono la memorizzazione dei dati dei lead nelle tue collezioni Firestore, la ricerca del profilo di un utente autenticato tramite ID, la verifica dello stato di un ordine o di una prenotazione dal backend della tua app e l'invio di notifiche push ai dispositivi di un utente quando la conversazione raggiunge una tappa fondamentale (ordine confermato, appuntamento prenotato, ticket di assistenza risolto). Il blocco gestisce automaticamente autenticazione, caching dei token e instradamento degli errori, così che tu debba solo scegliere un'operazione e compilare i campi che le servono.

Prerequisiti

Prima di aggiungere il blocco Firebase a un flusso, assicurati di avere:

• Un progetto Firebase con Cloud Firestore abilitato. Il Realtime Database non è supportato in questo blocco (la v1 copre solo Firestore).
• Una chiave JSON di service account scaricata dal tuo progetto Firebase. Nella Firebase Console vai su Impostazioni progetto, apri la scheda Account di servizio e clicca su Genera nuova chiave privata. Salva il file JSON scaricato. Ne incollerai il contenuto in ChatMaxima nel passaggio successivo.
• FCM configurato sulla tua app client se prevedi di inviare notifiche push. Ogni dispositivo dovrebbe essere registrato con Firebase e il suo token di registrazione FCM memorizzato in un punto da cui il bot possa recuperarlo (tipicamente un array Firestore users/{user_id}.tokens).

Nota: La chiave del service account è un segreto a lunga durata. Trattala allo stesso modo in cui tratti la password di un database di produzione. Non inserirla nel controllo del codice sorgente né condividerla in chat.

Passaggio 1: Connetti Firebase come integrazione

1. Vai su Dashboard → Integrazioni e clicca su Aggiungi integrazione
2. Seleziona Firebase dal menu a tendina delle piattaforme
3. Inserisci un nome (per esempio, Production Firebase o My App Firestore) così da poterlo riconoscere in seguito
4. Incolla l'intero contenuto del file JSON del service account nel campo Service Account JSON
5. Clicca su Verifica e salva

ChatMaxima valida la credenziale firmando un JWT con la chiave privata, scambiandolo per un token di accesso OAuth ed effettuando una chiamata di prova all'endpoint listCollectionIds di Firestore. Se il progetto ha Firestore abilitato e il service account ha accesso, vedrai Integrazione Firebase connessa. L'integrazione è ora disponibile per ogni bot del tuo team.

Nota: Il token di accesso viene memorizzato nella cache all'interno di ChatMaxima e aggiornato automaticamente prima della sua scadenza. Non è necessario ruotare o reinserire il JSON del service account a meno che tu non voglia passare a un progetto Firebase diverso.

Passaggio 2: Aggiungi il blocco Firebase a un flusso

1. Apri il tuo chatbot in Studio
2. Fai clic con il tasto destro sulla canvas (o trascina dalla barra laterale sinistra) e scegli Firebase sotto Integrazioni esterne
3. Fai doppio clic sul blocco per aprire la sua configurazione
4. Seleziona l'integrazione che hai creato al Passaggio 1 dal menu a tendina Seleziona integrazione
5. Scegli un'operazione e compila i campi descritti di seguito

Operazioni disponibili

Il blocco Firebase supporta sette operazioni. Le prime sei funzionano con Cloud Firestore. La settima invia una notifica push di Cloud Messaging (FCM).

Operazione	Categoria	Cosa fa
Get Document	Firestore	Legge un singolo documento tramite collezione e ID documento
Add Document	Firestore	Crea un nuovo documento. Firestore genera automaticamente l'ID se lo lasci vuoto
Set Document	Firestore	Sovrascrive il documento a un ID specifico. Sostituisce tutti i campi
Update Document	Firestore	Unisce solo i campi che fornisci in un documento esistente
Delete Document	Firestore	Rimuove un documento a un ID specifico
Query Collection	Firestore	Filtra, ordina e limita una collezione di documenti
Send Notification	Cloud Messaging	Invia una notifica a un dispositivo, a molti dispositivi o a un topic

Ogni input (collezione, ID documento, valori dei campi, token FCM, titolo e corpo della notifica) supporta le variabili di ChatMaxima con la sintassi {variable}, così da poterli popolare da blocchi di domanda precedenti, chiamate API precedenti o dati ricevuti in un blocco Webhook.

Configurazione delle operazioni

Get Document

Legge un documento tramite ID. Usalo per cercare il profilo di un utente, recuperare lo stato corrente di un ordine o estrarre qualsiasi record di cui hai già l'ID.

Campo	Descrizione
Collezione	Nome della collezione Firestore (per esempio, users, orders). Scegli dall'elenco rilevato o digitane uno nuovo
ID documento	L'ID da leggere. Supporta variabili come {user_id}
Memorizza la risposta nella variabile	Nome della variabile ChatMaxima che contiene il risultato

Add Document

Crea un nuovo documento in una collezione. Lascia ID documento vuoto per far generare automaticamente l'ID a Firestore, oppure fornisci il tuo (per esempio, {lead_id}).

Campo	Descrizione
Collezione	Collezione di destinazione
ID documento (facoltativo)	Lascia vuoto per l'ID automatico, o fornisci un ID personalizzato
Mappatura dei campi	Righe chiave/valore. Le chiavi sono nomi di campo Firestore, i valori possono essere letterali o riferimenti {variable}
Memorizza la risposta nella variabile	Il documento salvato (con il suo ID generato) viene memorizzato qui

Set Document

Sovrascrive il documento in collection/document_id esattamente con i campi che elenchi. Qualsiasi campo precedentemente presente nel documento ma non nella tua mappatura viene rimosso. Usalo quando vuoi una sostituzione pulita anziché un'unione.

Update Document

Unisce solo i campi che fornisci in un documento esistente. I campi non presenti nella tua mappatura vengono lasciati intatti. Questa è l'operazione di scrittura più sicura per aggiornare in modo incrementale il profilo di un utente o un record di ordine.

Delete Document

Rimuove il documento in collection/document_id. La variabile di risposta conterrà {"success": true} se l'eliminazione è riuscita.

Query Collection

Esegue una query strutturata Firestore su una collezione. Supporta filtri, ordinamento e un limite di righe.

Campo	Descrizione
Collezione	Collezione da interrogare
Filtri della query	Righe di field, operator, value. Combinate con AND
Campo di ordinamento	Nome del campo facoltativo per cui ordinare
Direzione di ordinamento	Crescente o Decrescente
Limite	Numero massimo di documenti da restituire. Lascia vuoto per nessun limite

Operatori di filtro supportati:

Operatore	Significato
EQUAL	Il campo è uguale al valore
NOT_EQUAL	Il campo non è uguale al valore
LESS_THAN	Il campo è minore del valore
LESS_THAN_OR_EQUAL	Il campo è minore o uguale al valore
GREATER_THAN	Il campo è maggiore del valore
GREATER_THAN_OR_EQUAL	Il campo è maggiore o uguale al valore
ARRAY_CONTAINS	Il campo è un array che contiene il valore
IN	Il valore del campo è uno dei valori elencati
ARRAY_CONTAINS_ANY	L'array del campo contiene uno qualsiasi dei valori elencati
NOT_IN	Il valore del campo non è nessuno dei valori elencati

Send Notification

Invia una notifica push FCM. Scegli uno di tre target:

Invia a	Quando usarlo
Un singolo dispositivo	Un token di registrazione FCM specifico
Più dispositivi	Multicast verso molti token in un unico passaggio. Accetta una variabile che si risolve in un array JSON, una stringa separata da virgole o un array nativo
Un topic	Broadcast verso ogni dispositivo iscritto a un topic (per esempio, premium-users)

Campi di configurazione:

Campo	Descrizione
Token / Tokens / Topic FCM	Il destinatario, a seconda del tipo di target. Variabili supportate
Titolo della notifica	Titolo in grassetto mostrato nella notifica push
Corpo della notifica	Il testo del messaggio mostrato sotto il titolo
Payload di dati	Coppie chiave/valore facoltative consegnate silenziosamente insieme alla notifica. Utili per il deep linking (per esempio, screen=orders, order_id={order_id}). I valori vengono convertiti in stringa prima dell'invio, secondo le regole FCM

Formato della variabile di risposta

Ogni operazione memorizza un risultato JSON nella variabile che indichi in Memorizza la risposta nella variabile. I blocchi successivi possono referenziare i campi usando la notazione con punto, per esempio {user_data.data.email}.

Letture Firestore (Get Document)

{
  "id": "user_42",
  "name": "projects/my-project/databases/(default)/documents/users/user_42",
  "data": {
    "name": "Priya",
    "email": "priya@example.com",
    "tokens": ["iphone_tok", "ipad_tok"]
  },
  "create_time": "2026-04-20T10:30:00Z",
  "update_time": "2026-04-21T14:15:00Z"
}

Scritture Firestore (Add / Set / Update)

La stessa struttura di Get Document. Il campo id riflette l'ID finale del documento (generato automaticamente se non ne hai fornito uno).

Delete Firestore

{ "success": true }

Query Collection

Un array di oggetti documento, ciascuno con la struttura precedente:

[
  { "id": "order_1", "data": { "status": "confirmed", "amount": 900 }, "create_time": "..." },
  { "id": "order_2", "data": { "status": "confirmed", "amount": 1200 }, "create_time": "..." }
]

Send Notification (singolo / topic)

{
  "success": true,
  "message_name": "projects/my-project/messages/0:17045...",
  "target_type": "token",
  "target_value": "iphone_tok"
}

Send Notification (multicast)

{
  "success": true,
  "sent": 2,
  "failed": 1,
  "invalid_tokens": ["stale_tok"],
  "results": [
    { "token": "iphone_tok", "success": true, "message_name": "..." },
    { "token": "ipad_tok",   "success": true, "message_name": "..." },
    { "token": "stale_tok",  "success": false, "error": "Requested entity was not found.", "error_code": "UNREGISTERED" }
  ]
}

L'array invalid_tokens elenca i token che Firebase ha contrassegnato come obsoleti (UNREGISTERED, INVALID_ARGUMENT, NOT_FOUND). Usa un blocco Firebase successivo con Update Document per rimuoverli dalla tua collezione Firestore users così da smettere di indirizzarti a dispositivi inattivi.

Casi d'uso comuni

Notifica push di conferma ordine

Un cliente completa il checkout nell'app, e vuoi che il bot invii una conferma a ogni dispositivo che l'utente ha registrato.

1. Blocco Domanda: Cattura o verifica {user_id}
2. Blocco Firebase (Get Document): Collezione users, ID documento {user_id}, memorizza il risultato in {user_data}
3. Blocco Condizione: Si dirama su {order_status} == "confirmed"
4. Blocco Firebase (Send Notification, Più dispositivi): Tokens {user_data.data.tokens}, titolo Order confirmed, corpo Hi {user_data.data.name}, your order {order_id} is on its way
5. Blocco Messaggio: We have sent a confirmation to your devices

Scrivi i lead del chatbot in Firestore

Usa Firestore come fonte di verità per i lead in entrata così che la tua app mobile possa reagire in tempo reale.

1. Blocco Domanda: Chiedi {name}, {email}, {phone}
2. Blocco Firebase (Add Document): Collezione chatbot_leads, campi name={name}, email={email}, phone={phone}, source=chatbot
3. Blocco Messaggio: Thanks {name}, we will be in touch shortly

Controlla la disponibilità di una prenotazione

Prima di confermare una prenotazione, interroga Firestore per assicurarti che la fascia sia ancora libera.

1. Blocco Firebase (Query Collection): Collezione bookings, filtro slot_id EQUAL {slot_id} e status NOT_EQUAL cancelled, limite 1, memorizza in {existing_bookings}
2. Blocco Condizione: Si dirama in base al fatto che {existing_bookings} sia vuoto
3. Se vuoto: Blocco Firebase (Add Document) per creare la prenotazione, poi Blocco Messaggio per confermare
4. Se c'è una corrispondenza: Blocco Messaggio That slot was just taken, please pick another

Broadcast verso un topic

Invia un annuncio uno-a-molti a ogni dispositivo iscritto a un topic.

1. Blocco Trigger: L'amministratore attiva il flusso con una Campagna
2. Blocco Firebase (Send Notification, Topic): Topic premium-users, titolo New feature released, corpo Tap to try it out, dati screen=whats_new

Pulisci i token FCM obsoleti

Dopo un invio multicast, rimuovi i token inattivi dal profilo dell'utente così che i push futuri vadano solo ai dispositivi attivi.

1. Blocco Firebase (Send Notification, Più dispositivi): Memorizza il risultato in {push_result}
2. Blocco Condizione: Si dirama in base al fatto che {push_result.invalid_tokens} non sia vuoto
3. Blocco Codice o Blocco API: Calcola l'elenco dei token ripuliti
4. Blocco Firebase (Update Document): Collezione users, ID documento {user_id}, campo tokens={pruned_tokens}

Best practice

• Definisci correttamente l'ambito del service account. Crea un service account dedicato per ChatMaxima e assegnagli solo i ruoli Firestore e FCM di cui ha bisogno. Non usare la chiave predefinita dell'Admin SDK per la produzione
• Memorizza i token FCM come array. Gli utenti hanno spesso più dispositivi. Tenerli in un unico campo tokens per utente rende banali gli invii multicast
• Gestisci il ramo di errore. Ogni blocco Firebase ha un secondo output che si attiva quando l'operazione fallisce. Instradalo verso un messaggio di recupero o un nuovo tentativo, anziché lasciare che il flusso si blocchi
• Rimuovi i token obsoleti. FCM restituisce UNREGISTERED quando un token è inattivo. Usa il campo invalid_tokens nella risposta multicast per ripulire i profili dei tuoi utenti
• Mantieni piccoli i valori del payload di dati. FCM richiede che tutti i valori del payload di dati siano stringhe e che la dimensione totale del messaggio resti sotto i 4 KB. ChatMaxima converte automaticamente i valori in stringa, ma i blob JSON di grandi dimensioni verranno rifiutati da Firebase
• Non far trapelare il JSON del service account. Una volta salvato in ChatMaxima, il JSON non viene riesposto nell'interfaccia. Tratta il file scaricato con la stessa cura di qualsiasi altro segreto di produzione

Domande frequenti

Quali prodotti Firebase supporta il blocco?

Cloud Firestore (lettura / scrittura / query) e Cloud Messaging (FCM HTTP v1 API). Realtime Database, Firebase Authentication, Cloud Functions e In-App Messaging non sono gestiti da questo blocco.

Posso usare lo stesso blocco sia per Firestore sia per FCM?

Sì. Una singola credenziale di integrazione Firebase autorizza entrambi i prodotti. Posiziona blocchi Firebase separati per ogni operazione di cui hai bisogno (per esempio, un blocco Get Document per cercare i token dell'utente, poi un blocco Send Notification per inviare a quei token).

Dove viene memorizzato il JSON del mio service account?

All'interno della tabella chatbot_integration_tokens, con ambito limitato al tuo team. Il JSON non viene mai restituito al browser dopo il salvataggio. ChatMaxima lo usa lato server per generare token di accesso OAuth a breve durata per Firebase.

Perché la notifica arriva ma il payload di dati manca?

FCM richiede che i valori del payload di dati siano stringhe. Se passi una variabile numerica o booleana direttamente, ChatMaxima la converte in stringa per te, ma alcune app client si aspettano formati specifici. Ricontrolla come la tua app legge RemoteMessage.getData() su Android o userInfo su iOS.

Il mio invio multicast mostra che alcuni token sono falliti. Cosa devo fare?

Guarda l'array invalid_tokens nella variabile di risposta. Questi sono token che Firebase considera inattivi. Usa un blocco Update Document per rimuoverli dall'array tokens dell'utente in Firestore così da non indirizzarli di nuovo.

Il blocco può inviare a un ID utente invece che a un token FCM?

Non direttamente. FCM indirizza i dispositivi tramite token di registrazione, non tramite utente. Il pattern normale è: memorizza i token dell'utente in Firestore sotto users/{user_id}, usa un blocco Get Document per recuperarli, poi passa l'array di token al blocco Send Notification.

Posso interrogare le sottocollezioni?

Il blocco attuale interroga le collezioni di primo livello. Le query annidate o di sottocollezione (per esempio, users/{uid}/orders) sono in roadmap. Come soluzione alternativa, memorizza dati denormalizzati in una collezione di primo livello con chiave l'ID utente.

Come testo il blocco prima della messa in produzione?

Crea un progetto Firebase sandbox con alcuni documenti di prova. Connettilo come integrazione ChatMaxima separata, indirizza il blocco verso di esso ed esegui il flusso dalla modalità Anteprima in Studio. Passa il blocco all'integrazione di produzione una volta che sei soddisfatto.

Risoluzione dei problemi

"Verifica e salva" fallisce con "Credenziale rifiutata da Firestore"

1. Apri il tuo progetto Firebase e conferma che Cloud Firestore sia abilitato (Console → Firestore Database)
2. Controlla che il service account abbia almeno il ruolo Cloud Datastore User (IAM → Account di servizio)
3. Assicurati di aver incollato l'intero file JSON, incluso il campo private_key con gli escape di nuova riga \n intatti
4. Rigenera la chiave privata se il file originale è stato modificato o copiato parzialmente

Il blocco mostra "Integrazione Firebase non trovata"

1. Conferma che l'integrazione esista sotto Dashboard → Integrazioni e sia attiva
2. Se hai creato l'integrazione di recente, aggiorna il modale del blocco usando il pulsante di aggiornamento accanto al menu a tendina dell'integrazione
3. Elimina e ricrea l'integrazione se la credenziale è stata ruotata in Firebase

Firestore restituisce "Documento non trovato" (404)

1. Verifica che il nome della collezione sia scritto esattamente come appare in Firebase (sensibile alle maiuscole)
2. Controlla l'ID documento. Se proviene da una variabile, ispeziona il log della conversazione per vedere il valore effettivo che viene sostituito
3. Ricorda che Firestore tratta un documento mancante in modo diverso da uno vuoto. Il blocco restituisce not_found: true nella variabile di risposta così da poterti diramare su di esso

La notifica FCM non arriva sul dispositivo

1. Conferma che il token FCM sia valido. I token scadono quando l'app viene disinstallata o reinstallata
2. Controlla che il dispositivo abbia le autorizzazioni per le notifiche concesse alla tua app
3. Ispeziona la variabile di risposta. Un invio riuscito restituisce message_name. Un fallimento restituisce error e spesso un error_code come UNREGISTERED
4. Verifica che il dispositivo non sia in modalità risparmio energetico o bloccato dal Non disturbare a livello di sistema

L'invio al topic riesce ma nessuno lo riceve

1. La consegna ai topic è best-effort e può richiedere fino a un minuto
2. Conferma che i dispositivi si siano effettivamente iscritti al topic (messaging().subscribeToTopic('premium-users') sul client)
3. I nomi dei topic sono sensibili alle maiuscole e non possono iniziare con /topics/ nella v1 API. Usa solo il nome, per esempio premium-users

La variabile di risposta è vuota

1. Assicurati di aver compilato il campo Memorizza la risposta nella variabile sul blocco
2. Controlla che il nome della variabile non entri in conflitto con una parola chiave riservata o con la variabile di un altro blocco
3. Ispeziona il log della conversazione per vedere il risultato grezzo della chiamata Firebase

Prossimi passi

• Blocco API - Chiama qualsiasi API REST esterna dal tuo flusso
• Blocco Webhook - Ricevi chiamate HTTP in entrata nel tuo flusso
• Blocco Condizione - Dirama il flusso in base ai valori delle variabili
• Panoramica di Studio - Esplora tutti i tipi di blocco e le funzionalità del flow builder