Bloc Firebase - Firestore et Cloud Messaging dans votre chatbot

Vue d'ensemble

Le bloc Firebase connecte votre chatbot ChatMaxima directement à un projet Firebase. Il permet à votre flux de lire et d'écrire des documents dans Cloud Firestore et d'envoyer des notifications push FCM aux utilisateurs de votre application mobile ou web, le tout depuis un seul bloc. Toute opération que vous configurez s'exécute exactement au point de la conversation où vous déposez le bloc, afin que votre bot puisse extraire des données de Firestore, y stocker un état, ou déclencher une notification push en réponse à un état spécifique de la conversation.

Les cas d'usage typiques incluent le stockage des données de leads dans vos propres collections Firestore, la recherche du profil d'un utilisateur authentifié par ID, la vérification du statut d'une commande ou d'une réservation depuis le backend de votre application, et l'envoi de notifications aux appareils d'un utilisateur lorsque la conversation atteint un jalon (commande confirmée, rendez-vous pris, ticket de support résolu). Le bloc gère automatiquement l'authentification, la mise en cache des jetons et l'acheminement des erreurs, vous n'avez donc qu'à choisir une opération et à remplir les champs qui comptent pour elle.

Prérequis

Avant d'ajouter le bloc Firebase à un flux, assurez-vous de disposer de :

• Un projet Firebase avec Cloud Firestore activé. Realtime Database n'est pas pris en charge dans ce bloc (la v1 couvre uniquement Firestore).
• Une clé JSON de compte de service téléchargée depuis votre projet Firebase. Dans la console Firebase, allez dans Paramètres du projet, ouvrez l'onglet Comptes de service et cliquez sur Générer une nouvelle clé privée. Enregistrez le fichier JSON téléchargé. Vous collerez son contenu dans ChatMaxima à l'étape suivante.
• FCM configuré sur votre application cliente si vous prévoyez d'envoyer des notifications push. Chaque appareil doit être enregistré auprès de Firebase et son jeton d'enregistrement FCM stocké à un endroit que le bot peut récupérer (généralement un tableau Firestore users/{user_id}.tokens).

Remarque : La clé de compte de service est un secret de longue durée. Traitez-la de la même manière qu'un mot de passe de base de données de production. Ne la versionnez pas dans le contrôle de source et ne la partagez pas dans une discussion.

Étape 1 : Connectez Firebase en tant qu'intégration

1. Allez dans Tableau de bord → Intégrations et cliquez sur Ajouter une intégration
2. Sélectionnez Firebase dans la liste déroulante des plateformes
3. Saisissez un nom (par exemple, Production Firebase ou My App Firestore) afin de pouvoir le reconnaître plus tard
4. Collez le contenu complet du fichier JSON de compte de service dans le champ JSON du compte de service
5. Cliquez sur Vérifier et enregistrer

ChatMaxima valide l'identifiant en signant un JWT avec la clé privée, en l'échangeant contre un jeton d'accès OAuth et en effectuant un appel test au point de terminaison listCollectionIds de Firestore. Si le projet a Firestore activé et que le compte de service y a accès, vous verrez Intégration Firebase connectée. L'intégration est désormais disponible pour chaque bot de votre équipe.

Remarque : Le jeton d'accès est mis en cache à l'intérieur de ChatMaxima et actualisé automatiquement avant son expiration. Vous n'avez pas besoin de renouveler ou de ressaisir le JSON du compte de service, sauf si vous souhaitez passer à un autre projet Firebase.

Étape 2 : Ajoutez le bloc Firebase à un flux

1. Ouvrez votre chatbot dans Studio
2. Faites un clic droit sur le canevas (ou glissez depuis la barre latérale gauche) et choisissez Firebase sous Intégrations externes
3. Double-cliquez sur le bloc pour ouvrir sa configuration
4. Sélectionnez l'intégration que vous avez créée à l'étape 1 dans la liste déroulante Sélectionner l'intégration
5. Choisissez une opération et remplissez les champs décrits ci-dessous

Opérations disponibles

Le bloc Firebase prend en charge sept opérations. Les six premières fonctionnent avec Cloud Firestore. La septième envoie une notification push Cloud Messaging (FCM).

Opération	Catégorie	Ce qu'elle fait
Get Document	Firestore	Lit un seul document par collection et ID de document
Add Document	Firestore	Crée un nouveau document. Firestore génère l'ID automatiquement si vous le laissez vide
Set Document	Firestore	Remplace le document à un ID spécifique. Remplace tous les champs
Update Document	Firestore	Fusionne uniquement les champs que vous fournissez dans un document existant
Delete Document	Firestore	Supprime un document à un ID spécifique
Query Collection	Firestore	Filtre, ordonne et limite une collection de documents
Send Notification	Cloud Messaging	Pousse une notification vers un appareil, plusieurs appareils ou un sujet

Chaque entrée (collection, ID de document, valeurs de champ, jeton FCM, titre et corps de notification) prend en charge les variables ChatMaxima avec la syntaxe {variable}, vous pouvez donc les renseigner à partir de blocs de question précédents, d'appels API antérieurs ou de données reçues dans un bloc Webhook.

Configuration des opérations

Get Document

Lit un document par ID. Utilisez-le pour rechercher le profil d'un utilisateur, récupérer l'état actuel d'une commande ou extraire tout enregistrement dont vous avez déjà l'ID.

Champ	Description
Collection	Nom de la collection Firestore (par exemple, users, orders). Choisissez dans la liste détectée ou tapez-en une nouvelle
Document ID	L'ID à lire. Prend en charge les variables comme {user_id}
Stocker la réponse dans la variable	Nom de la variable ChatMaxima qui contient le résultat

Add Document

Crée un nouveau document dans une collection. Laissez Document ID vide pour laisser Firestore en générer un automatiquement, ou fournissez le vôtre (par exemple, {lead_id}).

Champ	Description
Collection	Collection cible
Document ID (facultatif)	Laissez vide pour un ID automatique, ou fournissez un ID personnalisé
Mappage de champs	Lignes clé/valeur. Les clés sont des noms de champs Firestore, les valeurs peuvent être des littéraux ou des références {variable}
Stocker la réponse dans la variable	Le document enregistré (avec son ID généré) est stocké ici

Set Document

Remplace le document à collection/document_id par exactement les champs que vous listez. Tous les champs précédemment présents sur le document mais absents de votre mappage sont supprimés. Utilisez-le lorsque vous voulez un remplacement net plutôt qu'une fusion.

Update Document

Fusionne uniquement les champs que vous fournissez dans un document existant. Les champs absents de votre mappage restent intacts. C'est l'opération d'écriture la plus sûre pour mettre à jour de manière incrémentale le profil d'un utilisateur ou un enregistrement de commande.

Delete Document

Supprime le document à collection/document_id. La variable de réponse contiendra {"success": true} si la suppression a réussi.

Query Collection

Exécute une requête structurée Firestore sur une collection. Prend en charge les filtres, l'ordre et une limite de lignes.

Champ	Description
Collection	Collection à interroger
Filtres de requête	Lignes de field, operator, value. Combinés avec AND
Champ Order By	Nom de champ facultatif pour trier
Sens de l'ordre	Croissant ou Décroissant
Limite	Nombre maximal de documents à renvoyer. Laissez vide pour aucune limite

Opérateurs de filtre pris en charge :

Opérateur	Signification
EQUAL	Le champ est égal à la valeur
NOT_EQUAL	Le champ n'est pas égal à la valeur
LESS_THAN	Le champ est inférieur à la valeur
LESS_THAN_OR_EQUAL	Le champ est inférieur ou égal à la valeur
GREATER_THAN	Le champ est supérieur à la valeur
GREATER_THAN_OR_EQUAL	Le champ est supérieur ou égal à la valeur
ARRAY_CONTAINS	Le champ est un tableau qui contient la valeur
IN	La valeur du champ est l'une des valeurs listées
ARRAY_CONTAINS_ANY	Le tableau du champ contient l'une des valeurs listées
NOT_IN	La valeur du champ n'est aucune des valeurs listées

Send Notification

Envoie une notification push FCM. Choisissez l'une des trois cibles :

Envoyer à	Quand l'utiliser
Un seul appareil	Un jeton d'enregistrement FCM spécifique
Plusieurs appareils	Multicast vers de nombreux jetons en une seule étape. Accepte une variable qui se résout en un tableau JSON, une chaîne séparée par des virgules ou un tableau natif
Un sujet	Diffusion vers chaque appareil abonné à un sujet (par exemple, premium-users)

Champs de configuration :

Champ	Description
Jeton(s) FCM / Sujet	Le destinataire, selon le type de cible. Variables prises en charge
Titre de la notification	Titre en gras affiché dans la notification push
Corps de la notification	Texte du message affiché sous le titre
Charge utile de données	Paires clé/valeur facultatives livrées silencieusement avec la notification. Utile pour le deep linking (par exemple, screen=orders, order_id={order_id}). Les valeurs sont converties en chaîne avant l'envoi, conformément aux règles FCM

Format de la variable de réponse

Chaque opération stocke un résultat JSON dans la variable que vous nommez sous Stocker la réponse dans la variable. Les blocs en aval peuvent référencer des champs avec la notation par points, par exemple {user_data.data.email}.

Lectures 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"
}

Écritures Firestore (Add / Set / Update)

La même forme que Get Document. Le champ id reflète l'ID final du document (généré automatiquement si vous n'en avez pas fourni).

Suppression Firestore

{ "success": true }

Query Collection

Un tableau d'objets document, chacun avec la forme ci-dessus :

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

Send Notification (simple / sujet)

{
  "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" }
  ]
}

Le tableau invalid_tokens liste les jetons que Firebase a signalés comme obsolètes (UNREGISTERED, INVALID_ARGUMENT, NOT_FOUND). Utilisez un bloc Firebase de suivi avec Update Document pour les supprimer de votre propre collection Firestore users afin de cesser de cibler les appareils morts.

Cas d'usage courants

Notification push de confirmation de commande

Un client finalise son achat dans l'application, et vous voulez que le bot pousse une confirmation vers chaque appareil que l'utilisateur a enregistré.

1. Bloc Question : Capturez ou vérifiez {user_id}
2. Bloc Firebase (Get Document) : Collection users, Document ID {user_id}, stockez le résultat dans {user_data}
3. Bloc Condition : Branchez sur {order_status} == "confirmed"
4. Bloc Firebase (Send Notification, Plusieurs appareils) : Jetons {user_data.data.tokens}, titre Order confirmed, corps Hi {user_data.data.name}, your order {order_id} is on its way
5. Bloc Message : We have sent a confirmation to your devices

Écrire les leads du chatbot dans Firestore

Utilisez Firestore comme source de vérité pour les leads entrants afin que votre propre application mobile puisse réagir en temps réel.

1. Bloc Question : Demandez {name}, {email}, {phone}
2. Bloc Firebase (Add Document) : Collection chatbot_leads, champs name={name}, email={email}, phone={phone}, source=chatbot
3. Bloc Message : Thanks {name}, we will be in touch shortly

Vérifier la disponibilité d'une réservation

Avant de confirmer une réservation, interrogez Firestore pour vous assurer que le créneau est toujours libre.

1. Bloc Firebase (Query Collection) : Collection bookings, filtre slot_id EQUAL {slot_id} et status NOT_EQUAL cancelled, limite 1, stockez dans {existing_bookings}
2. Bloc Condition : Branchez selon que {existing_bookings} est vide
3. Si vide : Bloc Firebase (Add Document) pour créer la réservation, puis Bloc Message pour confirmer
4. Si correspondance : Bloc Message That slot was just taken, please pick another

Diffuser vers un sujet

Envoyez une annonce un-à-plusieurs à chaque appareil abonné à un sujet.

1. Bloc Déclencheur : Un administrateur déclenche le flux avec une campagne
2. Bloc Firebase (Send Notification, Sujet) : Sujet premium-users, titre New feature released, corps Tap to try it out, données screen=whats_new

Nettoyer les jetons FCM obsolètes

Après un envoi multicast, supprimez les jetons morts du profil de l'utilisateur afin que les futurs envois ne ciblent que les appareils actifs.

1. Bloc Firebase (Send Notification, Plusieurs appareils) : Stockez le résultat dans {push_result}
2. Bloc Condition : Branchez selon que {push_result.invalid_tokens} est non vide
3. Bloc Code ou Bloc API : Calculez la liste de jetons élaguée
4. Bloc Firebase (Update Document) : Collection users, Document ID {user_id}, champ tokens={pruned_tokens}

Bonnes pratiques

• Limitez correctement les droits du compte de service. Créez un compte de service dédié à ChatMaxima et donnez-lui uniquement les rôles Firestore et FCM dont il a besoin. N'utilisez pas la clé Admin SDK par défaut en production
• Stockez les jetons FCM sous forme de tableau. Les utilisateurs ont souvent plusieurs appareils. Les conserver dans un seul champ tokens par utilisateur rend les envois multicast triviaux
• Gérez la branche d'erreur. Chaque bloc Firebase a une seconde sortie qui se déclenche en cas d'échec de l'opération. Acheminez-la vers un message de récupération ou une nouvelle tentative, plutôt que de laisser le flux se bloquer
• Élaguez les jetons obsolètes. FCM renvoie UNREGISTERED quand un jeton est mort. Utilisez le champ invalid_tokens de la réponse multicast pour nettoyer vos profils utilisateurs
• Gardez les valeurs de charge utile de données petites. FCM exige que toutes les valeurs de charge utile de données soient des chaînes et que la taille totale du message reste sous 4 Ko. ChatMaxima convertit les valeurs en chaîne automatiquement, mais les gros blocs JSON seront rejetés par Firebase
• Ne divulguez pas le JSON du compte de service. Une fois enregistré dans ChatMaxima, le JSON n'est pas réexposé dans l'interface. Traitez le fichier téléchargé avec le même soin que tout autre secret de production

Foire aux questions

Quels produits Firebase le bloc prend-il en charge ?

Cloud Firestore (lecture / écriture / requête) et Cloud Messaging (API FCM HTTP v1). Realtime Database, Firebase Authentication, Cloud Functions et In-App Messaging ne sont pas gérés par ce bloc.

Puis-je utiliser le même bloc pour Firestore et FCM ?

Oui. Un seul identifiant d'intégration Firebase autorise les deux produits. Déposez des blocs Firebase distincts pour chaque opération dont vous avez besoin (par exemple, un bloc Get Document pour rechercher les jetons de l'utilisateur, puis un bloc Send Notification pour pousser vers ces jetons).

Où est stocké mon JSON de compte de service ?

À l'intérieur de la table chatbot_integration_tokens, limitée à votre équipe. Le JSON n'est jamais renvoyé au navigateur après l'enregistrement. ChatMaxima l'utilise côté serveur pour générer des jetons d'accès OAuth de courte durée pour Firebase.

Pourquoi la notification arrive-t-elle mais la charge utile de données est-elle absente ?

FCM exige que les valeurs de charge utile de données soient des chaînes. Si vous passez directement une variable numérique ou booléenne, ChatMaxima la convertit en chaîne pour vous, mais certaines applications clientes attendent des formats spécifiques. Vérifiez comment votre application lit RemoteMessage.getData() sur Android ou userInfo sur iOS.

Mon envoi multicast indique que certains jetons ont échoué. Que faire ?

Regardez le tableau invalid_tokens dans la variable de réponse. Ce sont des jetons que Firebase considère comme morts. Utilisez un bloc Update Document pour les retirer du tableau tokens de l'utilisateur dans Firestore afin qu'ils ne soient pas reciblés.

Le bloc peut-il envoyer vers un ID utilisateur au lieu d'un jeton FCM ?

Pas directement. FCM adresse les appareils par jeton d'enregistrement, pas par utilisateur. Le schéma normal est : stockez les jetons de l'utilisateur dans Firestore sous users/{user_id}, utilisez un bloc Get Document pour les récupérer, puis passez le tableau de jetons au bloc Send Notification.

Puis-je interroger des sous-collections ?

Le bloc actuel interroge les collections de premier niveau. Les requêtes imbriquées ou sur sous-collections (par exemple, users/{uid}/orders) sont sur la feuille de route. En contournement, stockez des données dénormalisées dans une collection de premier niveau indexée par ID utilisateur.

Comment tester le bloc avant la mise en production ?

Créez un projet Firebase bac à sable avec quelques documents de test. Connectez-le comme intégration ChatMaxima distincte, pointez le bloc dessus et exécutez le flux depuis le mode Aperçu dans Studio. Basculez le bloc vers l'intégration de production une fois que vous êtes satisfait.

Dépannage

Vérifier et enregistrer échoue avec « Identifiant rejeté par Firestore »

1. Ouvrez votre projet Firebase et confirmez que Cloud Firestore est activé (Console → Firestore Database)
2. Vérifiez que le compte de service a au moins le rôle Cloud Datastore User (IAM → Comptes de service)
3. Assurez-vous d'avoir collé le fichier JSON entier, y compris le champ private_key avec les échappements de saut de ligne \n intacts
4. Régénérez la clé privée si le fichier original a été modifié ou partiellement copié

Le bloc affiche « Intégration Firebase introuvable »

1. Confirmez que l'intégration existe sous Tableau de bord → Intégrations et est active
2. Si vous avez créé l'intégration récemment, actualisez la fenêtre du bloc avec le bouton d'actualisation à côté de la liste déroulante d'intégration
3. Supprimez et recréez l'intégration si l'identifiant a été renouvelé dans Firebase

Firestore renvoie « Document introuvable » (404)

1. Vérifiez que le nom de la collection est écrit exactement comme il apparaît dans Firebase (sensible à la casse)
2. Vérifiez l'ID du document. S'il provient d'une variable, inspectez le journal de conversation pour voir la valeur réellement substituée
3. Rappelez-vous que Firestore traite un document manquant différemment d'un document vide. Le bloc renvoie not_found: true dans la variable de réponse afin que vous puissiez brancher dessus

La notification FCM n'arrive pas sur l'appareil

1. Confirmez que le jeton FCM est valide. Les jetons expirent lorsque l'application est désinstallée ou réinstallée
2. Vérifiez que l'appareil a les autorisations de notification accordées pour votre application
3. Inspectez la variable de réponse. Un envoi réussi renvoie message_name. Un échec renvoie error et souvent un error_code comme UNREGISTERED
4. Vérifiez que l'appareil n'est pas en mode économie de batterie ou bloqué par le mode Ne pas déranger au niveau système

L'envoi vers un sujet réussit mais personne ne le reçoit

1. La livraison vers un sujet est en meilleur effort et peut prendre jusqu'à une minute
2. Confirmez que les appareils se sont réellement abonnés au sujet (messaging().subscribeToTopic('premium-users') côté client)
3. Les noms de sujet sont sensibles à la casse et ne peuvent pas commencer par /topics/ dans l'API v1. Utilisez juste le nom, par exemple premium-users

La variable de réponse est vide

1. Assurez-vous d'avoir rempli le champ Stocker la réponse dans la variable sur le bloc
2. Vérifiez que le nom de la variable n'entre pas en collision avec un mot-clé réservé ou la variable d'un autre bloc
3. Inspectez le journal de conversation pour voir le résultat brut de l'appel Firebase

Étapes suivantes

• Bloc API - Appelez n'importe quelle API REST externe depuis votre flux
• Bloc Webhook - Recevez des appels HTTP entrants dans votre flux
• Bloc Condition - Branchez le flux selon les valeurs de variables
• Vue d'ensemble de Studio - Explorez tous les types de blocs et les fonctionnalités du générateur de flux