Collections et données

Les collections sont les tables de données propres à votre bot. Elles permettent de stocker des demandes, commandes, réponses de dialogues, scores de jeu, inscriptions à des sessions — tout ce que le bot collecte auprès des utilisateurs ou reçoit via des intégrations. La section se trouve dans le menu gauche : Données → Collections.

Qu'est-ce qu'une collection

Une collection est composée de champs (schéma décrivant les colonnes) et d'enregistrements (lignes de données). Chaque enregistrement est un ensemble de valeurs correspondant aux champs de la collection ; en interne, il est stocké sous forme de document JSON flexible, ce qui permet à la collection d'évoluer sans problème lors de l'ajout de nouveaux champs.

Le nom d'une collection est unique au sein d'un bot et sert d'identifiant dans les actions des réactions (par exemple leads, orders, scores).

Types de champs

Lors de la création d'une collection, vous définissez la liste des champs et le type de chacun :

  • text — chaîne de caractères (nom, email, commentaire).
  • number — nombre (montant, quantité, score).
  • bool — oui/non (true / false).
  • datetime — date et heure.
  • json — objet imbriqué ou tableau pour des valeurs complexes.

Le type détermine la façon dont le champ est édité dans l'interface et comment la valeur est coercée à l'enregistrement. Le schéma n'est pas rigide : si un enregistrement contient un champ hors schéma, il est sauvegardé et affiché dans une colonne séparée.

Création d'une collection

  1. Ouvrez Données → Collections et cliquez sur Ajouter.
  2. Saisissez un nom (en caractères latins, sans espaces — plus facile à référencer dans les réactions).
  3. Avec le bouton Champ, ajoutez les colonnes nécessaires et sélectionnez le type de chacune.
  4. Si nécessaire, définissez les règles de rétention (voir ci-dessous) et sauvegardez.

Enregistrements : consultation et modification

Sur la carte de la collection, un bouton avec une icône de tableau ouvre la fenêtre Données avec les enregistrements de cette collection :

  • Consultation — toutes les lignes sont affichées en liste, un champ par cellule, en commençant par les plus récentes.
  • Ajouter un enregistrement — ouvre un formulaire selon le schéma de la collection ; chaque champ est éditable selon son type (interrupteur pour bool, champ de saisie JSON pour json, etc.).
  • Modifier (crayon) — modifie une ligne existante.
  • Supprimer (corbeille) — supprime une ligne.

Les enregistrements sont également remplis automatiquement par les actions des réactions du bot (voir ci-dessous). La modification manuelle et l'écriture automatique opèrent sur la même collection.

Rétention

Pour éviter une croissance illimitée de la collection, définissez des règles de nettoyage automatique :

  • Conserver au maximum N enregistrements — en cas de dépassement, les enregistrements les plus anciens sont supprimés.
  • Conserver pendant N jours au maximum — les enregistrements plus anciens que la durée indiquée sont supprimés.

Le nettoyage est effectué périodiquement par un processus en arrière-plan ; les règles peuvent être combinées.

Utilisation des données depuis les réactions

Les collections sont directement liées au constructeur de réactions. Les actions disponibles dans une réaction sont :

  • Créer un enregistrement — ajoute une ligne ; les valeurs proviennent de templates (par exemple {{user.id}}, {{message.text}}). Vous pouvez définir une clé de déduplication pour que les appels répétés mettent à jour la même ligne plutôt que de créer des doublons.
  • Mettre à jour des enregistrements — modifie les lignes correspondant à une condition.
  • Interroger des enregistrements — lit les lignes dans le contexte d'exécution sous forme de tableau, pour les parcourir ensuite.
  • Supprimer des enregistrements — supprime les lignes selon une condition.
  • Boucle (for-each) — parcourt le tableau du contexte et exécute des actions imbriquées pour chaque élément (par exemple, envoyer un message à une liste issue d'une collection).

Ainsi, le bot peut gérer un CRM, accumuler des demandes, attribuer des points et générer des rapports sans base de données externe.

Accès depuis une Mini App

Les enregistrements d'une collection peuvent être lus depuis la Telegram Mini App de votre bot : le frontend interroge les données de la collection par son nom, avec des filtres et une limite. Cela permet d'afficher à l'utilisateur ses commandes, son historique ou un classement directement dans Telegram.

Conseils

  • Donnez aux champs des noms courts en format machine (email, total, paid) — plus pratiques à insérer dans les templates des réactions.
  • Pour un enregistrement idempotent (par exemple « une seule demande par utilisateur »), utilisez la clé de déduplication.
  • Activez la rétention pour les logs et les données temporaires afin que la collection ne grossisse pas indéfiniment.
  • Le type json convient lorsque la structure de la valeur n'est pas fixée à l'avance.