Tarea (Task)

Introducción

La Tarea (Task) es la capacidad de mensajería proactiva del Agente: es el Agente quien inicia la conversación con el usuario, en lugar de esperar a que el usuario hable primero.

A diferencia de la conversación habitual, que sigue el esquema "el usuario pregunta → el Agente responde", la tarea funciona así: "la plataforma, según las condiciones que hayas definido, envía un mensaje al Agente en nombre del usuario → el Agente genera una respuesta → la respuesta se envía al usuario". El "mensaje de activación" que rellenas en la tarea es, en esencia, una frase enviada al Agente en lugar del usuario; el Agente generará una respuesta como si hubiera recibido un mensaje real de un usuario, y lo que el usuario final ve es la respuesta del Agente, no el mensaje de activación en sí.

Escenarios de uso típicos:

Requisitos previos

• Las tareas solo se envían a usuarios que ya han mantenido una conversación con el Agente. La plataforma localiza, para cada usuario, la conversación en la que estuvo "activo por última vez" en el canal de destino e inyecta el mensaje en esa conversación. Los usuarios sin registro de conversación no recibirán el mensaje de la tarea (en el detalle de ejecución se registra como NO_CONVERSATION).
• Si el canal de destino es una integración de terceros (como WhatsApp, Telegram, LINE, etc.), asegúrate de que la integración correspondiente esté correctamente configurada y habilitada en «Integrations»; si la integración está desactivada o las credenciales han caducado, el envío fallará (CHANNEL_CONFIG_INVALID / CHANNEL_AUTH_FAILED).
• La ejecución de una tarea invoca el LLM del Agente para generar la respuesta, por lo que consume créditos (Credits) con normalidad.

Acceso

Entra en Espacio de desarrollo → Agente → selecciona un Agente → menú lateral izquierdo «Tasks».

La lista de tareas permite: buscar por nombre de tarea y filtrar por estado (Status), tipo de activación (Trigger) y usuarios de destino (Target). Descripción de los campos de la lista:

Crear una tarea

Haz clic en New task en la esquina superior derecha y completa la configuración en el panel lateral derecho.

1. Información básica

Atención: al seleccionar All users aparecerá una confirmación adicional, ya que implica difundir el mensaje a todos los usuarios de todos los canales de este Agente. Asegúrate de que el rango de conversaciones de destino esté configurado de forma razonable para evitar envíos por error.

Canales de destino admitidos

Consejo: algunos canales no admiten por ahora el envío proactivo desde el servidor debido a las limitaciones del protocolo de la plataforma (por ejemplo, Discord, DingTalk, SoBot); aparecerán atenuados en el desplegable de canales con la indicación del motivo. En los canales propios (Web / Widget, etc.), la respuesta se escribe directamente en la conversación y el usuario la verá la próxima vez que abra la ventana de chat; en los canales de mensajería instantánea y las plataformas de atención al cliente, la respuesta se envía proactivamente al usuario a través de la API de la plataforma correspondiente.

2. Modo de activación (Trigger)

El modo de activación determina "cuándo se envía". Existen tres modos:

Activa - Programada (Active - Scheduled)

La plataforma inicia el envío según el calendario definido; adecuado para boletines periódicos y notificaciones únicas.

La hora se calcula según la zona horaria seleccionada en la tarea. Tras crearse, una tarea programada queda en estado WAITING y pasa a RUNNING cuando llega la hora de la primera ejecución; una tarea Once pasa automáticamente a COMPLETED al finalizar su ejecución.

Activa - Por evento (Active - Event)

Se activa cuando tu sistema de negocio llama a la plataforma mediante un Webhook; adecuado para integrarse con eventos de negocio como pedidos, pagos o tickets.

Al crear la tarea, selecciona el método de autenticación y rellena las credenciales; la plataforma generará automáticamente una URL de Webhook única (que podrás consultar en el detalle de la tarea una vez creada):

Ejemplo de llamada al Webhook

La URL del Webhook tiene la forma {dominio de la plataforma}/bot/proactive-task/webhook/{webhookPath}; utiliza la dirección completa que se muestra en el detalle de la tarea.

                      
                      POST {Webhook URL}
Content-Type: application/json
Authorization: Basic base64(username:password)

{
  "idempotency_key": "order-20260903-0001",
  "target": {
    "channel": "TELEGRAM",
    "user_id": "customer_123"
  },
  "variables": {
    "order_no": "SO-20260903-0001",
    "eta": "5 de septiembre"
  }
}

                    

Atención: que la solicitud al Webhook se procese correctamente solo significa que "se ha recibido y se ha añadido a la cola de envío"; consulta el resultado real del envío en el historial de ejecución. Los casos de fallo de autenticación, tarea detenida o canal de destino fuera del rango de canales de destino de la tarea devuelven un error de permisos. Cada dirección de Webhook tiene un límite de 120 llamadas por minuto.

Pasiva - Activada por usuario (Passive - User Triggered)

La plataforma analiza cada minuto a todos los usuarios de destino y activa el envío para los usuarios que cumplen las reglas; adecuado para escenarios como la reactivación de usuarios inactivos o el seguimiento de usuarios de alto valor.

Configuración de reglas

Haz clic en Add rule para añadir reglas; entre varias reglas puedes elegir AND (deben cumplirse todas) u OR (basta con que se cumpla una).

Nota: los atributos de usuario provienen de «Gestión de variables → Atributos de usuario» y se evalúan usuario por usuario (si el usuario no tiene valor definido, se toma el valor por defecto del atributo); son adecuados para filtrar por perfil de usuario. Los atributos personalizados provienen de «Gestión de variables → Variables personalizadas»; son valores unificados a nivel de Agente, iguales para todos los usuarios, y resultan adecuados como condiciones de tipo "interruptor general". Todos los campos de las reglas se evalúan a partir de la conversación en la que el usuario estuvo activo por última vez en el canal de destino.

Control de frecuencia de mensajes (Message Frequency)

Las tareas de activación pasiva deben configurar un control de frecuencia: dentro de la ventana definida (N horas / N días), un mismo usuario solo podrá ser activado una vez por esta tarea, para evitar molestar repetidamente a los usuarios que cumplen las reglas de forma continua.

Consejo: la hora de la última conversación del usuario (User's last chat time) es un momento "pasado", por lo que debes usar operadores del tipo "han pasado N unidades"; los operadores del tipo "dentro de N unidades a partir de ahora" solo se aplican a campos de fecha futura (como la fecha de vencimiento de una suscripción) y, si se usan con la hora de la última conversación, nunca coincidirán.

3. Mensaje de activación (Message)

Introduce el contenido del mensaje que se enviará al Agente "en nombre del usuario". El Agente generará una respuesta a partir de este mensaje, junto con su propio prompt, base de conocimiento, etc., y después la enviará al usuario.

Puedes usar {{variable}} para referenciar las siguientes variables:

Ejemplos

• Boletín programado: Resúmeme las noticias más importantes del sector de hoy con un tono breve y cercano.
• Reactivación de usuarios inactivos: Llevo varios días sin pasarme por aquí; salúdame de forma proactiva y cuéntame qué novedades hay últimamente.
• Notificación por evento: Mi pedido {{event.variables.order_no}} ya se ha enviado y está previsto que llegue el {{event.variables.eta}}; indícame la información logística y recuérdame que esté atento a la entrega.

Consejo: el mensaje de activación es una pregunta escrita "desde la perspectiva del usuario" dirigida al Agente, no un texto que se muestre directamente al usuario. Si quieres que el Agente lo transmita lo más literalmente posible, indícalo expresamente en el mensaje, por ejemplo: "Dile al usuario textualmente: …".

Una vez comprobado que todo es correcto, haz clic en Create.

Atención: cada Agente puede tener como máximo 10 tareas simultáneamente en estado WAITING / RUNNING; si se supera este límite, deberás detener alguna o esperar a que finalicen las tareas existentes.

Estado de la tarea

Ver la tarea y el historial de ejecución

Haz clic en View en la lista para acceder al detalle de la tarea, que contiene dos pestañas:

• Configuration: vista de solo lectura de la configuración de la tarea. En las tareas por evento, aquí puedes consultar la URL del Webhook y la información de autenticación.
• Execution History: registro de cada ejecución, con la hora de ejecución, el número de destinatarios, el número de éxitos / fallos y la tasa de éxito.

Haz clic en una ejecución para ver el detalle de ejecución: estadísticas de éxitos / fallos por canal y el registro de cada envío individual. Descripción de los motivos de fallo:

Detener y eliminar

• Stop: las tareas en estado WAITING / RUNNING / ERROR pueden detenerse en cualquier momento; tras detenerse pasan a TERMINATED y no se pueden reanudar.
• Delete: solo pueden eliminarse las tareas en estado COMPLETED / TERMINATED; al eliminarlas se borran también el historial y el detalle de ejecución.

Preguntas frecuentes

P: ¿Por qué la tarea se ejecuta correctamente, pero el contenido que ve el usuario no es el mensaje de activación que he introducido?
El mensaje de activación es "una pregunta enviada al Agente en nombre del usuario"; lo que el usuario ve es la respuesta que el Agente genera a partir de esa frase. Si necesitas controlar el texto con exactitud, pide expresamente al Agente en el mensaje de activación que lo reproduzca literalmente.

P: ¿Los usuarios nuevos recibirán los mensajes de la tarea?
No. Las tareas solo se envían a usuarios con registro de conversación previo, y la fecha de creación de la conversación debe estar dentro del "rango de conversaciones de destino".

P: ¿Por qué la tarea programada no se ha enviado exactamente a la hora en punto?
El planificador realiza un análisis cada minuto y, además, los envíos masivos se realizan por lotes según el límite de velocidad a nivel de proyecto, por lo que la hora real de llegada puede retrasarse ligeramente.

P: ¿El Webhook devuelve un error de permisos (Permission deny)?
Comprueba, en este orden: que la URL del Webhook sea correcta, que las credenciales de autenticación coincidan, que la tarea no haya sido detenida y que el target.channel de la solicitud pertenezca a los canales de destino configurados en la tarea.