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

## 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" }`.

## 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.
- **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](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-es)
- [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-es)
- [Canal API: el contrato estructurado de eventos](/hc/ajuda/articles/api-developers-api-channel-contract-es)