I. Aperçu Fonctionnel

La « Liste des Utilisateurs » est le centre de profils utilisateurs à l'échelle d'un Agent (agent) unique. Elle permet aux équipes opérationnelles et aux développeurs de consulter :

• Quels utilisateurs finaux ont eu une interaction significative avec ce Agent ;
• L'identité de chaque utilisateur (userId / ID anonyme) ;
• Le nombre d'événements clés générés par chaque utilisateur ;
• Les heures d'activité de chaque utilisateur (premier contact, dernière activité).
• Pour plus d'informations sur le système des utilisateurs, consultez : Aperçu de l'Utilisateur.

Accès : Console Développeur → Entrer dans un Agent → Gestion des Utilisateurs (User Manage) → Utilisateurs (Users).

II. Règles de la Liste des Utilisateurs

Règle fondamentale : seuls les utilisateurs ayant généré au moins un « événement clé » à l'intérieur de ce Agent apparaîtront dans la liste des utilisateurs.

2.1 Comment la liste des utilisateurs est-elle alimentée

Le système gère une « liste des utilisateurs » qui est alimentée par deux types de déclencheurs :

Autrement dit, un visiteur qui a simplement envoyé des messages sans déclencher d'événement clé n'apparaîtra pas dans la liste des utilisateurs ; ce n'est qu'au moment où le grand modèle de langage extrait au moins un événement clé d'une conversation, ou qu'un événement clé est créé manuellement via API/UI, que cet utilisateur sera « exposé » dans la vue opérationnelle.

2.2 Pourquoi utiliser les événements clés comme critère d'inclusion

Les événements clés sont des fragments factuels que le système identifie comme ayant une valeur métier après extraction sémantique du contenu d'une conversation (par exemple « retrait », « plainte », « litige », « ouverture de compte réussie », etc.). En adoptant « avoir produit un événement clé » comme critère d'inclusion, on garantit que :

• La liste se concentre sur les utilisateurs ayant une réelle valeur métier, sans être noyée par le bruit des visiteurs occasionnels ;
• Les colonnes « nombre d'événements clés » et « dernière activité » du profil utilisateur restent comparables ;
• Les actions opérationnelles ultérieures (marquage de traitement, relance par appel sortant) disposent d'un point d'ancrage événementiel clair.

2.3 Comment les événements clés sont-ils produits

Les événements clés proviennent de trois types de déclencheurs :

• REALTIME (temps réel) : déclenche automatiquement l'extraction après chaque nouveau message dans une conversation ;
• SCHEDULED (planifié) : extraction de complément des conversations historiques selon une planification ;
• MANUAL (manuel) : clic manuel sur « Extraire » dans la page de détail d'une conversation.

Le processus d'extraction est effectué par le LLM en classifiant selon le « dictionnaire des types d'événements » et les règles métier configurés pour le Agent courant, et produit quatre types d'opérations : CREATE / UPDATE / MERGE / DELETE.

Par conséquent, si vous souhaitez voir davantage d'utilisateurs apparaître dans la liste d'un Agent, vous devez d'abord vérifier :
① Si l'extraction d'événements clés est activée pour ce Agent ;
② Si le dictionnaire des types d'événements couvre bien les scénarios métier qui vous intéressent.

III. Identifiants : userId et ID anonymes

3.1 Définition des champs

3.2 Règle de priorité

Lorsque le système identifie « le même utilisateur », il applique la règle suivante :

Si userId est présent, userId fait foi ; en l'absence de userId, on retombe sur AnonymousId.

L'affichage de la colonne « Identité de l'utilisateur » dans l'interface respecte la même règle : userId est affiché en priorité, sinon AnonymousId, avec displayName (surnom) en sous-titre.

3.3 Relation entre les deux : passage de l'anonyme à l'utilisateur connecté

Le cycle de vie typique d'un utilisateur final est le suivant :

                      
                      Visiteur (uniquement anonymousId)  ──connexion/inscription──▶  Utilisateur enregistré (avec userId)

                    

La plateforme fournit bindUserId(botId, anonymousId, userId) pour la mise à niveau d'identité :

• Si ce userId n'existe pas encore sous ce Agent :
  • Écriture directe de userId sur le profil anonyme d'origine ;
  • Le primaryAnonymousId initial et la liste des ID anonymes sont conservés, les événements clés historiques restent rattachés au même profil.
• Si ce userId existe déjà sous ce Agent :
  • Tous les anonymousIds du profil anonyme courant sont fusionnés dans le profil de l'utilisateur connecté ;
  • Le profil anonyme est supprimé ;
  • On obtient ainsi l'expérience « accès anonyme d'abord → connexion à un ancien compte ensuite → fusion historique ».

Par conséquent, une ligne d'utilisateur visible dans la liste peut avoir traversé : ① plusieurs ID anonymes (effacements répétés des cookies / utilisation inter-appareils), ② et avoir finalement été liée au même userId. Le compteur affiché dans la colonne « ID anonyme » correspond à anonymousIds.length.

3.4 Comment les événements clés sont rattachés à un utilisateur

L'entité d'événement clé (c_bot_event) contient également les champs userId et anonymousId. Lors de la consultation des événements dans le tiroir de détail utilisateur, les règles de correspondance sont :

• Lorsque l'utilisateur a déjà un userId : seuls les événements où event.userId == userId sont interrogés ;
• Lorsque l'utilisateur n'a qu'un ID anonyme : on interroge les événements où event.userId n'existe pas et event.anonymousId == primaryAnonymousId.

Cela garantit que : un utilisateur enregistré après mise à niveau peut voir tous les événements rattachés à son userId ; un utilisateur anonyme non encore mis à niveau ne voit que les événements de son propre périmètre anonyme, sans agrégation erronée.

IV. Champs temporels : Premier contact vs Dernière activité

4.1 Définition des champs

4.2 Règles d'écriture

• Premier contact : écrit une seule fois lors de la création initiale de l'utilisateur dans la liste, et ne change jamais ensuite. À comprendre comme « le point de départ de la rencontre entre cet utilisateur et ce Agent ».
• Dernière activité : actualisée à l'heure courante à chacun des événements suivants :
  • L'utilisateur a envoyé un message dans ce Agent ;
  • Un nouvel événement clé a été généré pour cet utilisateur ;
  • Le statut d'un événement clé a changé ;
  • Les informations de contact (numéro de téléphone / surnom) ont été complétées.

4.3 Sens métier

4.4 Tri par défaut de la liste

La liste des utilisateurs est triée par défaut par ordre décroissant de la dernière heure d'activité : les utilisateurs ayant eu la plus récente activité apparaissent en premier.
Les deux colonnes temporelles peuvent être triées numériquement en cliquant sur l'en-tête.

V. Aperçu des champs de la liste

VI. Guide d'utilisation

6.1 Recherche d'utilisateurs

Le champ de recherche par mot-clé en haut de la page prend en charge quatre types de correspondance (un seul match suffit) :

Remarque : userId / ID anonyme ne prennent pas en charge la recherche floue, vous devez saisir la valeur complète.
Le nom d'affichage et le numéro de téléphone prennent en charge la recherche floue.

6.2 Consulter les événements clés d'un utilisateur

En cliquant sur le nombre dans la colonne « Événements clés » de la ligne utilisateur (ou sur « Voir » en fin de ligne), le tiroir de droite récupère les événements paginés selon les conditions suivantes :

• Périmètre utilisateur : filtrage par userId ou ID anonyme selon la règle de la section 3.4 ;
• Filtres secondaires pris en charge : catégorie d'événement, statut, mot-clé (basé sur une regex sur le résumé d'événement) ;
• Tri par défaut par ordre décroissant de l'heure d'événement ;

Colonnes du tiroir d'événements : catégorie d'événement, résumé d'événement, statut, priorité, confiance, heure de mise à jour.

6.3 Valeurs possibles pour le statut, la priorité et la confiance

6.4 Actions opérationnelles courantes

• Suivi des nouveaux utilisateurs : filtrer les utilisateurs ayant eu un premier contact dans les N derniers jours ;
• Réveil des utilisateurs dormants : combiné avec un filtrage par catégorie d'événement clé pour identifier les utilisateurs ayant effectué des actions à forte valeur mais qui ne sont plus actifs ;
• Liste des événements non traités : dans le tiroir de détail utilisateur, filtrer par « statut = À traiter / En cours », puis effectuer une relance en lot.

VII. Questions Fréquentes (FAQ)

Q1 : Je vois un utilisateur ayant envoyé beaucoup de messages sur le frontend, mais je ne le retrouve pas dans la liste des utilisateurs ?
R : La liste des utilisateurs n'affiche que « les utilisateurs ayant produit un événement clé ». Si l'extraction d'événements clés n'est pas activée pour cet Agent, ou si le résultat de l'extraction est vide (le contenu des messages ne correspond à aucun type d'événement configuré), cet utilisateur n'apparaîtra pas dans la liste. Vérifiez l'interrupteur « Extraction d'événements clés » de l'Agent et le dictionnaire des types d'événements. De plus, les conversations effectuées dans Espace Développement-Debug ne sont pas utilisées pour l'extraction d'événements clés et ne sont pas non plus affichées dans la liste des utilisateurs.

Q2 : Pourquoi un même utilisateur réel apparaît-il parfois en tant qu'ID anonyme et parfois en tant que userId ?
R : Avant la connexion, le SDK génère un ID anonyme pour gérer la session de l'utilisateur final ; après la connexion, l'intégrateur doit transmettre le userId métier. Le système fusionne alors le profil anonyme dans le profil userId via bindUserId, et c'est la ligne userId que vous verrez ensuite dans la liste ; l'ID anonyme d'origine est conservé dans la liste anonymousIds pour permettre la traçabilité.

Q3 : La « dernière activité » diverge de l'heure la plus récente dans les tables de conversation/messages ?
R : Le profil fait foi. La dernière heure d'activité est rafraîchie aux quatre moments suivants : arrivée d'un message, création d'événement, changement de statut d'événement, mise à jour des informations de contact ; en cas d'écart, c'est en général parce qu'une opération a emprunté un chemin non standard (par exemple une importation hors ligne).

Q4 : Le « premier contact » peut-il être modifié ?
R : Non. Ce champ n'est persisté qu'à la première création, et aucune mise à jour ultérieure ne le modifiera.

Q5 : Quelle est la relation entre la liste des utilisateurs et la liste des conversations ?
R : La liste des conversations (dimension conversationId) enregistre chaque échange ; la liste des utilisateurs (dimension userId / anonymousId) est une agrégation à la dimension de la personne au-dessus des conversations. Un utilisateur peut correspondre à plusieurs conversations ; un événement clé est nécessairement rattaché à une conversation, et nécessairement à un profil utilisateur.