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

| Situación | Opción desactivada/omitida | Opción activada |
|---|---|---|
| Mensaje del cliente, sin responsable | Se entrega | Se entrega |
| Mensaje del cliente, con responsable humano | No se entrega | Se entrega |
| Mensaje de salida o evento de ciclo de vida | Se entrega | Se entrega |

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

```json
{
  "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](/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)