Documentación de ayuda

1. Gestión de Agentes — Visión general

Para qué sirve

La sección Agents permite administrar los agentes telefónicos/virtuales que ejecutan campañas de llamadas: crear nuevos agentes, configurar su comportamiento, diseñar la fuente de contactos, controlar horarios, definir tiempos de espera y revisar resultados y métricas.

Qué encontrará el cliente en esta área

• Vista principal con un listado (tabla) de agentes.
• Filtros para localizar agentes por fecha, horario, estado o resultado.
• Formulario para crear/editar agentes (tipo de llamada, ingesta de datos, horarios, reintentos, etc.).
• Acceso a perfiles individuales con pestañas de Información, Historial, Logs y Reportes.
   

Cómo usarlo — Paso a paso (flujo básico)

1. Iniciar sesión → Seleccionar Rootlenses Voice → Ir a Agents.
2. Revisar la lista de agentes y usar filtros para localizar elementos específicos.
3. Para crear: hacer clic en Agregar Agente → completar formulario → Guardar Cambios.
4. Para editar: abrir menú kebab (⁝) → seleccionar Editar → modificar y guardar.
5. Para deshabilitar/habilitar: menú kebab → elegir Deshabilitar o Habilitar.

Dudas comunes y puntos que debe verificar (checklist)

• ¿El título del agente es único y descriptivo?
• ¿Se usó la plantilla CSV correcta antes de subir contactos?
• ¿Los horarios y el timezone coinciden con la operación prevista?
• ¿Se verificaron los números de origen (proveedor) disponibles y activos?

2. Descripción de campos de la tabla de agentes (explicación detallada)

Nota: aquí se explican todos los campos tal como aparecen en la UI para que el cliente sepa interpretar cada valor.

• Título
  • ¿Qué es? Nombre identificador del agente.
  • ¿Para qué sirve? Identificar campañas o perfiles de llamada.
  • Configuración: usar nombres con prefijos que indiquen campaña y fecha (ej.: Ventas_Q4_2025).
• Fecha de creación
  • ¿Qué es? Marca temporal de creación (DD/MM/AAAA, HH:MM:SS).
  • Uso: control de auditoría y ordenación cronológica.
• Estado Operativo
  • Activo: agente enviando llamadas según su configuración.
  • Inactivo: agente pausado; no se ejecutan llamadas.
  • Recomendación: antes de activar, validar los settings y una muestra de contactos.
• Horario (inicio / fin)
  • Formato y uso: definir ventana en la que se permiten llamadas; respetar normativa local de horarios de contacto.
  • Verificación: comprobar que los horarios no solapen zonas horarias del target.
• Acciones (kebab ⁝)
  • Opciones: Editar, Deshabilitar, Habilitar.
  • Buenas prácticas: usar Editar para pequeños ajustes; deshabilitar agentes que ya no se usan para evitar llamadas no deseadas.

3. Filtros — Cómo y por qué usarlos (detallado)

Objetivo

Permiten reducir la lista de agentes para encontrar rápidamente uno o varios con características precisas.

Filtros disponibles y ejemplos de uso

• Fecha de creación: buscar agentes creados en una campaña determinada.
  • Ejemplo: 01/10/2025 ó 31/10/2025 para “Campaña Octubre”.
• Hora de inicio / Hora de fin: localizar agentes que operan en franjas específicas.
• Estado: ver solo agentes activos/inactivos.
• Resultado: útil para identificar agentes con llamadas en curso (en progreso) o finalizar análisis de performance. 

Recomendaciones

• Combine Fecha + Estado para revisar agentes activos creados recientemente.
• Use Resultado para auditorías y para exportar campañas con X porcentaje de finalización.

4. Crear un agente — Formulario en detalle (campo por campo)

A continuación se explica cómo completar cada campo y qué efectos tiene.

Título

• ¿Qué ingresar? Nombre claro y único.
• Ejemplos: Agente_Ventas_Noviembre, Recordatorio_Pagos_Clientes.
• Verificación: evitar caracteres especiales que afecten exportaciones.

Tipo

• Llamada con IA — preguntas/respuestas dinámicas; interacción conversacional.
• Llamada de audio — reproducción de mensajes pregrabados.
• Configuración relacionada: si selecciona IA, deberá revisar CoT y RAG.

Data Ingestion Mechanic (Mecánica de ingesta)

• File CSV (procedimiento):
  • Descargar plantilla CSV (botón).
  • Abrir plantilla y mapear columnas obligatorias (ej.: phone, name, email, metadata).
  • Completar y validar interno (formato E.164 para números si aplica).
  • Seleccionar archivo → Subir → Validación del sistema.
  • Corregir errores indicados por la validación y volver a subir.
  • Recomendación: probar con un CSV pequeño (10–50 filas) antes de full load.

• ETL Script (procedimiento)
  • Selección de la opción ETL Script
    • El usuario marca la opción ETL Script en el módulo de Data Ingestion Mechanic.
    • Inmediatamente, la interfaz despliega cuatro campos clave:
      • Variables Globales
      • Script de Carga
      • Script de Transformación
      • Script de Salida
  • Definición de Variables Globales
    • El usuario define todas las variables que serán utilizadas en los scripts.
    • Estas variables pueden incluir:
      • Tokens de autenticación (Bearer tokens)
      • URLs de APIs
      • IDs para filtrado (por ejemplo, IDs de sprints)
      • Cualquier valor constante que los scripts necesiten
    • Todas estas variables quedan disponibles automáticamente para los tres scripts, evitando duplicación y errores de configuración.
  • Configuración del Script de Carga
    • El usuario ingresa el código o las instrucciones necesarias para extraer los datos crudos desde la fuente original.
    • Ejemplos de fuentes: CRM, API externa, base de datos interna.
    • El script debe obtener conjuntos de datos relevantes para la campaña, como listas de contactos, detalles de sprints u otros datos específicos.
  • Configuración del Script de Transformación
    • Aquí el usuario define cómo procesar y adaptar los datos obtenidos en el Script de Carga.
    • El objetivo es convertir la información cruda en un formato estructurado y compatible con Rootlenses AI, listo para procesamiento interno y ejecución de campañas.
    • Esto puede incluir limpieza de datos, normalización de campos, filtrado de registros o creación de estructuras específicas.
  • Configuración del Script de Salida
    • El usuario define cómo los datos procesados serán devueltos o sincronizados con la fuente original.
    • Ejemplos de acciones:
      • Actualización de estados en un CRM
      • Registro de resultados en una base de datos
      • Eliminación de contactos de un sprint si la llamada falló (estado failed)
  • Ejecución y validación
    • Una vez configurados los tres scripts y las variables globales, el sistema permite ejecutar un test de ETL para verificar que los datos se cargan, transforman y devuelven correctamente.
    • Se muestran logs y resultados parciales para validar cada paso antes de integrarlo a la campaña final.

Carga de CSV (UI)

• Botones: Descargar plantilla, Seleccionar archivo, Subir archivo.
• Comportamiento esperado: al subir, el sistema debe mostrar errores de parsing y filas rechazadas. 

Sistema Telefónico (Números de origen)

• Ingrese los números desde los cuales se realizarán las llamadas.
• Permite múltiples números separados por coma.
• Verificar que los números pertenezcan a proveedores con credenciales válidas y estén en estado activo.

Tiempo de espera entre llamadas

• Parámetros: Días (0–30+), Horas (0–23), Minutos (0–59).
• Efecto: evita contactar repetidamente al mismo número en un corto período.
• Recomendación: definir políticas de “cool-down” basadas en la campaña (ej.: recordatorios = 2 días; prospección = 7 días).

Horario de Ejecución

• Configurar ventana donde se permiten llamadas (formato AM/PM según UI).
• Considerar zonas horarias del público objetivo.
• Ejemplo: Inicio 9:00 AM, Fin 6:00 PM → llamadas solo en horario comercial.

Tiempo de espera en llamada (ring timeout)

• Rango: 10–30 segundos (incrementos de 5); recomendado 20s.
• Comportamiento: si no contestan en ese tiempo, la llamada se marca No Answer y finaliza.

Guardar y validación

• Al hacer clic en Guardar Cambios, el sistema valida: campos obligatorios, formato CSV (si aplica) y consistencia de parámetros.

5. Perfil del agente — Qué contiene y cómo usarlo

Propósito del perfil

Visualizar y gestionar la configuración completa del agente, analizar su historial de operación y diagnosticar incidentes con logs.

Pestañas y uso operativo

• Información: revisar configuración, cambiar parámetros, actualizar CoT o RAG.
• Historial de Llamadas: analizar interacciones por fecha, estado y resultados.
• Logs: investigar errores y warnings.
• Reportes: visualizar métricas de performance (KPI) — si aplica según la implementación.

Recomendaciones para administradores

• Antes de activar un agente: revisar Información → validar RAG y CoT → probar previsualización de voz.
• Para auditoría: exportar registros desde el Historial de Llamadas.

6. Chain of Thought (CoT) y Archivos RAG — Uso y configuración

¿Qué es CoT?

Es la lógica o flujo de razonamiento que la IA seguirá durante la llamada. Debe definirse claramente para controlar la conversación.

Campo CoT (cómo configurarlo)

• Paso 1: Ingresar o pegar el flujo de conversación en el campo de texto (ej.: saludo → verifica datos → ofrece opción A/B → cierre).
• Paso 2: Guardar con Guardar CoT.
• Verificación: probar una conversación de ejemplo en entorno de staging antes de producción.

¿Qué es RAG y cómo cargar archivos?

• RAG (Retrieval-Augmented Generation) permite que la IA consulte documentos (TXT/PDF) para responder con información contextual de la empresa.
• Carga: arrastrar y soltar o seleccionar archivos → Subir archivos RAG.
• Recomendación: mantener los documentos actualizados y nombrarlos con convenciones (ej.: FAQ_Productos_2025.pdf). El rag no es editable, se debe eliminar y subir uno nuevo ante cualquier modificación.

Previsualización de voz IA

• Seleccionar voz y idioma → ingresar texto → Enviar → escuchar preview.
• Usar para validar pronunciación, tonos y mensajes sensibles.

7. Historial de llamadas — Uso detallado y acciones recomendadas

Para qué sirve

Permite auditar interacciones, medir resultados y extraer información operativa de cada llamada.

Cómo filtrar y buscar

• Usar el buscador global para localizar por número o nombre.
• Filtrar por fecha/hora para segmentos temporales.
• Filtrar por estado (Completed, Failed, No Answer, Busy, etc.) para análisis de fallos o efectividad.
• Filtrar por Tipo (Todos, prueba, ETL,CSV)

Export y análisis

• Botón Export Results → genera CSV con los registros filtrados.
• Recomendación: exportar antes y después de grandes cambios de configuración para medir el impacto. 

Modal “Ver Detalles”

• Muestra información completa, análisis (nivel de interés), resumen automático y grabación.
• Acciones disponibles: escuchar, descargar audio, revisar conversación completa y logs vinculados. 

Qué revisar ante un problema en una llamada

• Estado de llamada (Failed, No Answer, Busy).
• Log asociado (abrir modal Ver Logs).
• Números de origen y credenciales del proveedor (ver módulo de Proveedores).
• Si es IA: verificar CoT y RAG.

8. Logs del sistema — Diagnóstico y buenas prácticas

Propósito

Registro técnico detallado que permite rastrear errores, warnings y mensajes informativos relacionados con la ejecución de llamadas y servicios asociados (ej.: adaptadores de telefónica, análisis de llamadas).

Filtros útiles

• Buscar por palabra clave del error.
• Filtrar por tipo de log: Error (prioritario), Warning, Message.
• Filtrar por entidad (ej.: Twilio Adapter, Call Analysis Service). 

Procedimiento ante un error

1. Localizar llamada afectada → Abrir Ver Logs.
2. Filtrar por error y ajustar rango horario.
3. Identificar entidad responsable y copiar trazas relevantes para soporte.
4. Si el error está relacionado con el proveedor: validar credenciales y estado del proveedor.