Base de connaissances GetMyBot

Collections et données

Stockez demandes, commandes et inscriptions dans GetMyBot : créez une table, ajoutez des données et utilisez-les dans les réactions.

Sur cette page

Une collection ressemble à une table : chaque ligne représente une demande, une commande ou une inscription. Le bot peut créer ces lignes à partir des réponses des utilisateurs ; vous pouvez les consulter et les modifier dans Données → Collections.

Pour des demandes de consultation, créez par exemple la collection leads avec les champs name, phone et topic. Après avoir posé ses questions, le bot garde le nom, le téléphone et le sujet dans une même ligne, que vous pourrez retrouver dans une réaction.

Qu'est-ce qu'une collection ?

Les champs définissent les colonnes, par exemple « Téléphone » et « Sujet ». Un enregistrement contient les valeurs d'une ligne. La liste des champs et de leurs types s'appelle le schéma. Techniquement, chaque enregistrement est un document JSON : ajouter un champ ne nécessite pas de recréer les lignes existantes.

Le nom d'une collection est unique pour un bot et sert d'identifiant dans les actions : leads, orders, scores, par exemple.

Types de champs

À la création, définissez les champs et leur type :

TypeContenuExemple
textChaîne de texteNom, e-mail ou commentaire
numberNombreMontant, quantité ou points
boolOui ou non : true / falseCommande payée ?
datetimeDate et heureHeure d'un cours
jsonObjet ou liste imbriquésArticles et propriétés d'une commande

Le type détermine le champ de saisie dans l'interface et la conversion de la valeur à l'enregistrement. Le schéma reste souple : un champ absent du schéma est quand même conservé et apparaît dans sa propre colonne.

Créer une collection

  1. Ouvrez Données → Collections et cliquez sur Ajouter.
  2. Donnez un nom, de préférence en lettres latines et sans espaces pour le réutiliser facilement dans les réactions.
  3. Ajoutez les colonnes avec Champ et choisissez leur type.
  4. Si nécessaire, réglez la durée de conservation ci-dessous, puis enregistrez.

Consulter et modifier les enregistrements

L'icône de table sur la carte de la collection ouvre la fenêtre Données :

  • Consulter : toutes les lignes sont affichées avec leurs champs, les plus récentes d'abord.
  • Ajouter un enregistrement : ouvre un formulaire selon le schéma, avec un contrôle adapté à chaque type, par exemple un commutateur pour bool ou une saisie JSON pour json.
  • Modifier (crayon) : change une ligne existante.
  • Supprimer (corbeille) : retire la ligne.

Les actions des réactions peuvent aussi remplir automatiquement cette même collection. La saisie manuelle et l'enregistrement automatique agissent sur les mêmes données.

Conservation (retention)

Pour éviter qu'une collection grossisse sans limite, définissez des règles de nettoyage :

  • Conserver au maximum N enregistrements : les plus anciens sont supprimés si la limite est dépassée.
  • Conserver au plus N jours : les enregistrements plus anciens sont supprimés.

Une durée de 30 jours convient par exemple à un journal temporaire. Le nettoyage est périodique, pas instantané à l'expiration. Vous pouvez activer les deux limites ensemble. N'imposez pas de durée aux commandes encore nécessaires.

Utiliser les données dans les réactions

Les collections sont directement reliées à l'éditeur de réactions :

  • Créer un enregistrement : ajoute une ligne à partir de substitutions telles que {{user_id}} et {{text}}. Une clé de déduplication évite les doublons : la même clé met à jour la ligne existante. La clé peut être l'ID utilisateur pour ne garder qu'une demande actuelle par personne.
  • Mettre à jour des enregistrements : modifie les lignes correspondant à un filtre.
  • Interroger les enregistrements : lit les lignes dans le contexte sous forme de tableau à parcourir.
  • Lire une page de collection (record_page) : charge les lignes par lots, par exemple deux fiches et un bouton « Page suivante ».
  • Agrégats de toute la collection (record_aggregate) : calcule nombre et sommes sur tous les enregistrements correspondants qui restent disponibles selon la politique de conservation. Charger seulement la première page ne limite pas ce calcul.
  • Transaction atomique des collections (collection_transaction) : vérifie les conditions et enregistre plusieurs changements ensemble, par exemple réserver une place et créer la demande. En cas de conflit, les changements précédents sont aussi annulés.
  • Supprimer des enregistrements : retire les lignes correspondant au filtre.
  • Boucle (for-each) : parcourt un tableau du contexte et exécute des actions pour chaque élément : mise à jour, calcul d'un total ou envoi à un service externe.

Le bot peut ainsi tenir un CRM, recueillir des demandes, attribuer des points et produire des rapports sans base de données externe.

Les exercices pratiques montrent comment poursuivre un catalogue, calculer le total de toutes les commandes correspondantes et réserver la dernière place. Une page de liste chargée, une page de collection et un agrégat de collection ne donnent pas les mêmes données à l'étape suivante.

Une boucle ne sert pas à diffuser des messages. Elle traite au maximum 500 éléments, tandis qu'un événement entier peut envoyer au maximum 50 messages. Si chaque élément envoie un message, les 50 premiers peuvent partir et les suivants sont refusés. Pour écrire aux personnes d'une collection, créez un segment, puis une diffusion, qui gère vitesse, pause et suivi. Voir Actions → Budget d'un événement.

Catalogue : rechercher, choisir, afficher une fiche

Pour commencer, suivez l'exercice de recherche d'un cours. Il montre les collections à préparer, l'ordre des actions et les tests pour zéro résultat, plusieurs résultats et un ancien bouton.

Dans un catalogue, gardez les données séparées des réactions. Par exemple, products contient name et aliases, tandis que variants contient product_id, name et card. Dans variants.product_id, activez Relation avec une autre collection, puis choisissez products, la clé _record_id et le libellé name. La relation décrit le rôle du champ ; elle ne modifie ni ne supprime les lignes en cascade.

  1. Dans la réaction au texte reçu, ajoutez Rechercher dans une collection (record_search). Choisissez products, la requête {{text}}, le champ de recherche name, les synonymes aliases, puis le nom de résultat search. Les synonymes peuvent être une chaîne ou un tableau JSON de chaînes. La recherche ignore la casse et la différence entre les lettres russes е et ё ; la ponctuation devient des espaces.
  2. Ajoutez Choisir l'étape suivante (branch_result) avec search comme source. La première branche correspondante s'exécute. Traitez d'abord un résultat incomplet en demandant de préciser la recherche, puis aucun résultat, correspondance approximative, un enregistrement et plusieurs enregistrements. Demandez confirmation pour une correspondance approximative. Un résultat vide ou unique n'est fiable que si la recherche est complète.
  3. Pour plusieurs résultats, ouvrez Boutons à partir des enregistrements trouvés dans le message. Choisissez search, le champ de libellé name et la réaction suivante. L'assistant renseigne buttons_from.over = search.rows, le modèle de libellé et carry.selected_id = {{item._record_id}}. Assurez-vous que le champ du libellé figure dans les champs renvoyés. L'éditeur avancé du bouton reste accessible.
  4. Dans la réaction suivante, ajoutez Trouver les enregistrements liés (record_related) : collection variants, clé product_id, valeur {{ctx.selected_id}}, résultat variants. Pour lire le produit choisi lui-même, utilisez products et _record_id. Si les relations reposent sur une autre clé métier, sélectionnez-la à la fois dans l'assistant de boutons et dans l'action de lecture.
  5. Choisissez à nouveau une branche selon le résultat. Affichez une seule fiche via {{ctx.variants.first.card}} ; proposez plusieurs variantes avec des boutons. Chaque bouton transmet un ID et les données à jour sont lues après le clic. Ne mettez pas la fiche ni d'autres champs modifiables dans carry.

Résultat d'une lecture

search.rows contient la liste plate des enregistrements, search.count le nombre de lignes chargées, search.first la première ligne et search.first.name un champ précis. Chaque ligne comporte aussi _record_id, _score et _match_type ; ces trois noms sont réservés. S'il n'y a aucun résultat, l'ancienne première ligne et ses champs sont effacés.

search.total compte les correspondances parmi les candidats examinés. total_exact = false signifie que la collection entière n'a pas été examinée ; truncated = true signale une limite de résultat. Dans ces cas, ne considérez pas le résultat comme exhaustif et ne garantissez pas la meilleure correspondance de toute la collection. Une requête examine au plus 10 000 lignes et 16 MiB ; la réponse indique les limites effectives. Elle retourne au plus 100 lignes par défaut, 10 000 au maximum.

Tester et comprendre la recherche

Dans l'éditeur, ouvrez Tester la recherche et saisissez une chaîne ou un ID concret. Cette opération ne fait que lire : elle ne lance ni réactions suivantes, ni messages, ni autres actions. Remplacez d'abord les substitutions des filtres supplémentaires par des valeurs concrètes. Le test affiche les lignes, le type de correspondance, le nombre de lignes examinées et les limites. Les anciens résultats sont masqués si le projet, la collection, les réglages ou les droits changent.

Le journal d'exécution indique les champs de recherche, le type de correspondance, les nombres de lignes examinées et renvoyées, les limites et la branche retenue. Le schéma de réaction étiquette toutes les conditions menant à une même réaction. En rouvrant une exécution, vous pouvez consulter l'explication de la recherche après l'événement correspondant si vous avez le droit d'en voir le contenu.

L'assistant crée au plus 20 boutons par défaut. Nombre maximum de boutons se règle de 1 à 100 : c'est une limite, pas une pagination. Une liste vide ne crée aucun bouton. Pour davantage de résultats, demandez à l'utilisateur de préciser sa recherche.

Dans Calcul, l'assistant Opération sur la liste chargée produit des formules pour le nombre de lignes, la première ligne, la somme d'un champ et la liste des libellés. Le calcul ne porte que sur les lignes chargées ; si le résultat est incomplet, il ne représente pas toute la collection.

API et MCP

Les mêmes opérations sont accessibles par POST /api/bots/{botID}/collections/{name}/search et /related, ainsi que par les outils MCP search_records et related_records avec le droit collections:read. Les appels restent limités au projet et à la région courants. Le test REST reçoit des valeurs concrètes ; les substitutions de modèles sont évaluées dans les actions des réactions.

Traiter un résultat et modifier sous condition

Transmettez un résultat de collection à list_transform pour filtrer, trier, dédupliquer ou choisir une page. list_aggregate calcule des agrégats nommés sur les lignes chargées, éventuellement par groupes. Ces actions fonctionnent aussi avec une liste normale provenant d'une réponse HTTP, sans collection.

Pour empêcher deux exécutions simultanées d'appliquer deux fois la même transition, utilisez record_update_if : précisez l'ID, les champs attendus et les nouvelles valeurs. Vérification et modification sont atomiques pour un enregistrement. Traitez le statut updated, conflict ou not_found avec branch_value. Cela diffère d'une mise à jour sans condition de toutes les lignes correspondant à un filtre.

Réglages, limites et exemples.

L'exercice de confirmation unique explique le contrôle du statut et du propriétaire, ainsi que les réponses distinctes pour updated, conflict et not_found.

Accès depuis une Mini App

La Mini App Telegram du bot peut lire les enregistrements d'une collection : son interface demande les données par nom de collection, avec filtres et limite. Elle peut afficher les commandes, l'historique ou un classement directement dans Telegram.

Conseils

  • Donnez aux champs des noms techniques courts (email, total, paid) pour les réutiliser dans les réactions.
  • Utilisez une clé de déduplication si rejouer une action ne doit pas créer une nouvelle ligne. Cette propriété s'appelle l'idempotence.
  • Définissez une durée de conservation (retention) pour les journaux et données temporaires devenus inutiles.
  • Le type json convient aux valeurs dont la structure varie.