Bots de atención y el canal de API

Abrir en

Conversa Labs

Última actualización el Jul 16, 2026

Visión general

Conversa Labs ofrece dos puntos de extensión complementarios para desarrolladores:

Canal de API: un inbox programable. En lugar de un canal listo (WhatsApp, correo, etc.), creas una bandeja de entrada de tipo API y conectas tu propia aplicación. Los mensajes de entrada llegan por la API REST y las respuestas de los agentes se entregan en tu webhook_url.
Agent bot: un bot vía webhook (bot_type: webhook). Se asigna a un inbox (de cualquier canal) y recibe los eventos de conversación/mensaje en su outgoing_url. El bot procesa el evento y puede responder llamando de vuelta a la API con su token de acceso.

Cuándo usar cada uno:

Usa el canal de API cuando necesites un canal a medida que la plataforma no ofrece de forma nativa.
Usa un agent bot cuando quieras automatizar respuestas (clasificación, respuestas automáticas, IA) antes o junto con la atención humana, en cualquier inbox.

Ambos se pueden combinar: un inbox de API que además tiene un agent bot asignado.

Permiso de administrador en la cuenta (crear inboxes y agent bots está restringido a admins).
Un endpoint HTTPS accesible para recibir webhooks (el webhook_url del canal y/o el outgoing_url del bot).
Un token de acceso válido para autenticar las llamadas a la API REST.

Crea un inbox de tipo API: ve a Configuración → Bandejas de entrada → Agregar → API. Indica un nombre y, opcionalmente, el webhook_url. Tras crearlo, anota el identifier generado para el canal.
Envía un mensaje de entrada: crea/abre una conversación en ese inbox y publica el mensaje del cliente vía API (POST .../conversations/:id/messages), autenticando con el token de acceso.
Configura el webhook_url del canal para recibir los mensajes de salida: cuando un agente responde en la conversación, el payload se entrega en tu endpoint.
(Opcional) Crea un agent bot: en Configuración → Agentes de IA/Agent bots, indica nombre, descripción y el outgoing_url (bot_type = webhook). Luego asigna el bot al inbox para que empiece a recibir los eventos de esa bandeja de entrada.

Token de acceso del bot: lo usa el bot para llamar de vuelta a la API (crear respuestas, reaccionar, actualizar estado). Se puede regenerar con reset_access_token.
Secreto del bot: se usa para firmar/verificar el payload del webhook enviado al outgoing_url. Se puede regenerar con reset_secret.
Verificación HMAC del canal (hmac_token, hmac_mandatory): valida la identidad del contacto. Con hmac_mandatory activo, los contactos solo se aceptan con un hash de identificación válido, calculado a partir del hmac_token.
Actualización de estado de mensaje: permitida solo en inboxes de API (por ejemplo, marcar entregado/leído o registrar un error de envío).
Payload del bot (webhook_data): identifica al bot en el evento con { id, name, type: "agent_bot" }.

Canal a medida: conectar una aplicación propia (una app interna, un marketplace, un canal propietario) como un inbox vía API.
Respuestas automáticas: un agent bot que hace la clasificación inicial, responde preguntas frecuentes y solo entonces pasa la conversación a un agente humano.

Verifica siempre la firma HMAC del webhook (canal y/o secreto del bot) antes de procesar el payload.
Garantiza la idempotencia: al crear mensajes de entrada, usa un source_id único para deduplicar reentregas.
Define un punto de traspaso claro del bot al humano (por ejemplo, asignar la conversación a un agente/equipo y dejar de responder con el bot).
Trata tokens y secretos como credenciales: nunca los expongas en el front-end.

401/403: token de acceso inválido, expirado o sin permiso.
El bot no recibe eventos: confirma que el outgoing_url es correcto y accesible, y que el bot está asignado al inbox.
HMAC inválido: el hash de identificación no coincide con el hmac_token; vuelve a calcular la firma y revisa el orden/codificación de los campos.