Saltar al contenido principal

Canales — Referencia Técnica

Esta página describe cómo funcionan los canales por debajo de la interfaz, en términos técnicos, para desarrolladores y usuarios con perfil técnico. Se centra en el modelo y en el comportamiento observable, no en detalles de implementación.

Modelo de arquitectura​

Un canal es la superficie donde un agente recibe mensajes y envía respuestas. La misma lógica del agente corre en todos los canales — lo que cambia es la forma de entrada (cómo llega un mensaje) y la forma de salida (qué puede mostrar el agente al responder).

Existen dos tipos de canales:

  • App web — el chat dentro del producto. Opciones de salida completas: vistas enriquecidas, visores de archivos, conjuntos de datos descargables, componentes interactivos.
  • Canales externos — WhatsApp, Instagram, Messenger, Telegram, Slack, Discord, Teams, web embed, widget y API. La salida se restringe a lo que cada plataforma admite (típicamente: texto, imágenes y archivos).

Cómo llega un mensaje entrante al agente​

Los canales externos entregan mensajes mediante una alerta automática (webhook) — el canal llama a una URL en la plataforma con cada mensaje nuevo. Cada agente conectado a ese canal tiene su propia dirección entrante; la dirección está protegida por una clave secreta para que nadie más pueda publicar mensajes falsos.

  • Cada canal externo tiene sus propias acciones de envío — enviar un mensaje en Telegram es una operación distinta a enviar uno en Slack, incluso cuando la intención del agente es la misma. La plataforma le expone al agente las acciones de envío correctas según el canal que disparó el turno.
  • Los canales web embed y API también pasan por este bucle pero con una solicitud autenticada más simple.

Serialización de la ejecución por sesión​

En la app web, la interfaz impide que el usuario envíe un segundo mensaje antes de que el agente termine de responder. Los canales externos no tienen esa restricción — los usuarios pueden enviar varios mensajes seguidos mientras el agente todavía está trabajando.

Para que la conversación no se corrompa a sí misma, se ejecuta un mensaje a la vez por conversación. Los mensajes que llegan mientras el agente está ocupado se encolan y se procesan cuando termina el turno en curso.

  • La serialización es por conversación, no por agente — dos conversaciones distintas del mismo agente siguen corriendo en paralelo.
  • Un bloqueo obsoleto (p. ej., un turno interrumpido) se libera automáticamente tras un tiempo acotado para que el siguiente mensaje no se quede esperando.

Archivos enviados en canales externos​

Cuando un usuario adjunta un archivo en un canal externo, el archivo se sube como un mensaje normal — no hay un mensaje de confirmación separado ("subido ✓"). El agente ve el archivo junto con la leyenda que el usuario haya escrito (o una leyenda por defecto si no hay) y decide qué hacer con él como parte de su razonamiento normal.

Esto hace que la conversación se sienta natural — el usuario solo envía una foto, el agente la mira y responde.

Reglas de salida por canal​

La respuesta del agente se filtra según lo que el canal admite:

CanalTextoImágenesArchivosComponentes enriquecidos
App web✓✓✓✓ (apps, visores, datasets)
WhatsApp / Instagram / Messenger✓✓✓— (se envía como texto o medios)
Telegram / Slack / Discord / Teams✓✓✓—
Web embed / widget✓✓✓—
API✓✓✓—

Cuando el agente intenta mostrar algo que el canal no puede renderizar, la plataforma lo degrada con elegancia (p. ej., una tarjeta de datos enriquecida se convierte en un resumen de texto compacto), de modo que la lógica del agente no necesita saber en qué canal corre.

Canales Meta — regla de uno por agente​

WhatsApp, Instagram y Messenger comparten un único inicio de sesión Meta por número / cuenta / Página. Como consecuencia:

  • Un número de WhatsApp Business puede estar conectado a un agente a la vez.
  • Una cuenta de Instagram puede estar conectada a un agente a la vez.
  • Una Página de Messenger puede estar conectada a un agente a la vez.

Reasignar uno de estos canales a otro agente lo desconecta del anterior.

Otros canales (Telegram, Slack, Discord, Teams) siguen las reglas de cada plataforma; en la práctica, cada credencial de bot/app también se dedica a un único agente.

Selección de canal en tiempo de ejecución del agente​

Cuando un agente corre, ve:

  • Las acciones de envío específicas del canal del canal que entregó el mensaje.
  • Una regla de salida consciente de la plataforma que limita lo que debería intentar mostrar.
  • Las mismas herramientas, conocimiento y skills que en cualquier otro canal — el canal nunca cambia las capacidades centrales del agente.

Así, una única definición de agente produce un comportamiento consistente en muchas superficies sin lógica específica por canal.

Límites y garantías​

  • El agente nunca ve el valor secreto de una credencial — solo el ID de la credencial que debe usar.
  • Los webhooks entrantes son rechazados si la clave secreta falta o es incorrecta.
  • Los mensajes dentro de una conversación están serializados; los mensajes de distintas conversaciones del mismo agente se procesan en paralelo.
  • Un canal Meta (número de WhatsApp, cuenta de Instagram, Página de Messenger) ↔ un agente.
  • El uso se mide como créditos por turno, igual que en la app web.

Qué sigue​