1. Resumen funcional

La «Lista de Usuarios» es el centro de perfiles de usuario en la dimensión de un único Agent (agente), pensado para que los equipos de operaciones y los desarrolladores puedan consultar:

• Qué usuarios finales han mantenido interacciones significativas con el Agent;
• Los identificadores de cada usuario (userId / ID anónimo);
• El número de eventos clave generados por cada usuario;
• Los tiempos de actividad de cada usuario (primer contacto, última actividad).
• Para más información sobre el sistema de usuarios, consulte: Visión general del Usuario.

Acceso: Consola de desarrollador → entrar en un Agent → Gestión de Usuarios (User Manage) → Usuarios (Users).

2. Reglas de la lista de usuarios

Regla principal: solo aparecerán en la lista de usuarios aquellos usuarios que hayan generado al menos un «evento clave» dentro del Agent.

2.1 Cómo se genera la lista de usuarios

Existe una «Lista de Usuarios» en el sistema, y los puntos que activan la entrada en dicha lista son de dos tipos:

Es decir, los visitantes que solo han enviado mensajes pero no han activado ningún evento clave no aparecerán en la lista de usuarios; un usuario solo se «expone» en la vista operativa cuando el modelo grande extrae al menos un evento clave de la conversación, o cuando se crea manualmente un evento clave a través de la API o la UI.

2.2 Por qué se usa el evento clave como criterio de entrada

Los eventos clave son fragmentos factuales con valor de negocio identificados por el sistema mediante extracción semántica del contenido de la conversación (por ejemplo, «retirada de fondos», «reclamación», «disputa», «alta de cuenta exitosa», etc.). Tomar «haber generado un evento clave» como criterio de entrada permite garantizar que:

• La lista se centra en usuarios con valor real de negocio, evitando el ruido de visitantes puntuales;
• Las columnas «número de eventos clave» y «última actividad» de cada fila sean comparables entre sí;
• Las acciones operativas posteriores (marcar como gestionado, llamadas de seguimiento) tengan un anclaje claro al evento.

2.3 Cómo se generan los eventos clave

Los eventos clave provienen de tres tipos de disparo:

• REALTIME (en tiempo real): la extracción se activa automáticamente cada vez que llegan mensajes nuevos a la conversación;
• SCHEDULED (programado): la extracción se realiza periódicamente sobre el historial de conversaciones;
• MANUAL (manual): se hace clic en «Extraer» manualmente desde la página de detalle de la conversación.

El proceso de extracción lo realiza el LLM, que clasifica según el «diccionario de tipos de evento» y las reglas de negocio configuradas para el Agent, y devuelve operaciones de cuatro tipos: CREATE / UPDATE / MERGE / DELETE.

Por tanto, si se desea que la lista de usuarios de un Agent muestre más usuarios, primero conviene comprobar:
① si el Agent tiene activada la extracción de eventos clave;
② si el diccionario de tipos de evento cubre los escenarios de negocio relevantes.

3. Identificadores: userId e ID anónimo

3.1 Definición de campos

3.2 Reglas de prioridad

Para localizar al «mismo usuario», el sistema sigue estas reglas:

Cuando hay userId, se utiliza el userId; cuando no hay userId, se recurre al AnonymousId.

La columna «Identidad del usuario» en la UI sigue la misma regla: muestra prioritariamente el userId; en su defecto, el AnonymousId, y usa el displayName (apodo) como subtítulo.

3.3 Relación entre ambos: de anónimo a usuario registrado

El ciclo de vida típico de un usuario final es:

                      
                      Visitante (solo anonymousId)  ──login/registro──▶  Usuario registrado (con userId)

                    

La plataforma proporciona bindUserId(botId, anonymousId, userId) para realizar la promoción de identidad:

• Si el userId aún no existe en este Agent:
  • Se escribe el userId directamente sobre el perfil anónimo original;
  • Se conservan el primaryAnonymousId original y la lista de IDs anónimos, y los eventos clave históricos siguen perteneciendo al mismo perfil.
• Si el userId ya existe en este Agent:
  • Se fusionan todos los anonymousIds del perfil anónimo actual en el perfil del usuario ya registrado;
  • Se elimina el perfil anónimo;
  • Se logra así la experiencia de «primero acceso anónimo → luego inicio de sesión en una cuenta antigua → fusión histórica».

Por tanto, una fila de la lista puede haber pasado por: ① varios IDs anónimos (debido a varias limpiezas de cookies / cambios de dispositivo) y ② finalmente quedar vinculada a un mismo userId. El indicador numérico de la columna «ID anónimo» corresponde a anonymousIds.length.

3.4 Cómo se atribuyen los eventos clave a los usuarios

La entidad de evento clave (c_bot_event) también dispone de los campos userId y anonymousId. Al consultar eventos en el panel lateral de detalle de usuario, las reglas de coincidencia son:

• Cuando el usuario ya tiene userId: solo se consultan eventos donde event.userId == userId;
• Cuando el usuario solo tiene un ID anónimo: se consultan eventos donde event.userId no exista y event.anonymousId == primaryAnonymousId.

Esto garantiza que: tras la promoción, los usuarios registrados ven todos los eventos asociados a su userId; los usuarios anónimos no promocionados solo ven los eventos de su propia dimensión anónima, sin agregaciones erróneas.

4. Campos de tiempo: primer contacto vs última actividad

4.1 Definición de campos

4.2 Reglas de escritura

• Primer contacto: se escribe una sola vez, cuando se crea por primera vez el registro de usuario, y no cambia jamás después. Puede entenderse como «el punto de inicio del conocimiento entre este usuario y el Agent».
• Última actividad: se actualiza al momento actual cada vez que ocurre alguno de los siguientes eventos:
  • El usuario envía un mensaje en este Agent;
  • El usuario genera un nuevo evento clave;
  • Cambia el estado de un evento clave;
  • Se complementa información de contacto (teléfono / apodo).

4.3 Significado de negocio

4.4 Orden por defecto de la lista

La lista de usuarios se muestra por defecto ordenada de forma descendente por la última actividad: los usuarios con movimientos más recientes aparecen al principio.
Ambas columnas de tiempo permiten ordenarse numéricamente al hacer clic en su cabecera.

5. Resumen de los campos de la lista

6. Guía de uso

6.1 Búsqueda de usuarios

El cuadro de búsqueda por palabras clave en la parte superior de la página admite cuatro tipos de coincidencia (basta con que cualquiera coincida):

Aviso: userId / ID anónimo no admiten búsqueda difusa, hay que introducir el valor completo.
El nombre visible y el teléfono sí admiten búsqueda difusa.

6.2 Ver los eventos clave de un usuario

Al hacer clic en el número de la columna «Eventos clave» de la fila de un usuario (o en «Ver» al final de la fila), el panel lateral derecho carga eventos paginados con los siguientes criterios:

• Ámbito de usuario: filtrado por userId o ID anónimo siguiendo las reglas de la sección 3.4;
• Permite filtros de segundo nivel: categoría de evento, estado y palabra clave (mediante regex sobre el resumen del evento);
• Por defecto se muestran ordenados de forma descendente por la fecha del evento.

Columnas del panel de eventos: categoría, resumen, estado, prioridad, confianza y fecha de actualización.

6.3 Valores de estado, prioridad y confianza

6.4 Acciones operativas habituales

• Seguimiento de nuevos usuarios: filtrar usuarios cuyo primer contacto haya sido en los últimos N días;
• Reactivación de usuarios dormidos: combinar el filtro de categorías de evento clave para localizar usuarios que han realizado acciones de alto valor pero ya no están activos;
• Listado de eventos sin resolver: dentro del panel lateral de detalle de usuario, filtrar por «estado = pendiente / en curso» y realizar el seguimiento por lotes.

7. Preguntas Frecuentes (FAQ)

Q1: He visto a un usuario enviar muchos mensajes desde el front-end, pero no aparece en la lista de usuarios. ¿Por qué?
R: La lista de usuarios solo muestra «usuarios que han generado eventos clave». Si el Agente no tiene activada la extracción de eventos clave o el resultado de la extracción está vacío (el contenido del mensaje no encaja con ningún tipo de evento configurado), el usuario no entrará en la lista. Compruebe el interruptor de «extracción de eventos clave» y el diccionario de tipos de evento del Agente. Las conversaciones de Debug en el espacio de desarrollo tampoco se utilizan para extraer eventos clave, y por lo tanto no aparecerán en la lista de usuarios.

Q2: ¿Por qué un mismo usuario real aparece a veces como ID anónimo y a veces como userId?
R: Antes de iniciar sesión, el usuario final mantiene la conversación con un ID anónimo generado por el SDK; tras iniciar sesión, la parte integradora debe transmitir el userId desde su sistema de negocio. El sistema fusiona el perfil anónimo con el perfil del userId mediante bindUserId, por lo que en la lista pasará a verse la fila del userId; los IDs anónimos originales se conservan en la lista anonymousIds para poder rastrearlos.

Q3: La «última actividad» no coincide con la fecha más reciente de la tabla de conversaciones/mensajes.
R: Prevalece el perfil. La fecha de última actividad se actualiza en cuatro momentos: llegada de un mensaje, creación de un evento, cambio de estado de un evento y actualización de información de contacto. Si hay diferencias, suele deberse a que alguna operación se realizó por una vía no estándar (por ejemplo, una importación offline).

Q4: ¿Se puede modificar el «primer contacto»?
R: No. Este campo se almacena solo en el momento de la creación inicial y ninguna actualización posterior lo sobrescribe.

Q5: ¿Cuál es la relación entre la lista de usuarios y la lista de conversaciones?
R: La lista de conversaciones (dimensión conversationId) registra cada conversación; la lista de usuarios (dimensión userId / anonymousId) es una agregación a nivel de persona por encima de las conversaciones. Un usuario puede tener varias conversaciones; un evento clave pertenece necesariamente a una conversación y a un perfil de usuario.