Bots de atención y el canal de API

Visión general

ConversaLabs 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.

Requisitos previos

• 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.

Paso a paso

1. 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.
2. 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.
3. 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.
4. (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.

Configuración y opciones

• 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" }.
• Mensajes con responsable (receive_incoming_when_assigned): su valor predeterminado es false. Cuando es true, un agent bot externo sigue recibiendo eventos de entrada message_created y message_updated aunque haya un agente humano asignado. La configuración pertenece al bot y se aplica a todas las bandejas vinculadas.

Activa la opción en el formulario del bot o envía el campo tipado mediante la API:

{
  "receive_incoming_when_assigned": true
}

El payload ya incluye conversation.assignee y conversation.assignee_type. Al activar la entrega, guarda el evento para conservar el contexto, pero no respondas mientras un humano atienda la conversación. La plataforma no bloquea automáticamente una respuesta creada con el token del bot. Maestro no usa esta opción: siempre recibe los eventos y aplica su propia política de pausa y retención.

Casos de uso

• 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.

Consejos, límites y buenas prácticas

• 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.

Solución de problemas

• 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. Si la conversación tiene un responsable humano, confirma también que receive_incoming_when_assigned está activado para ese bot.
• 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.

Ver también

• API REST, tokens y webhooks
• Eventos por módulo
• Canal API: el contrato estructurado de eventos