Webhooks (Avanzado)

El canal de Webhooks es una herramienta de integración avanzada que permite exponer un endpoint seguro para conectar a tu agente con cualquier sistema externo, aplicación móvil o plataforma personalizada que no cuente con una integración nativa en Atendium.

Integración y Exposición de Endpoint

Al activar este canal, Atendium genera un endpoint único para tu agente: POST https://webhook.atendium.com/webhook/custom/{channelId}

Este endpoint te permite enviar mensajes y eventos desde tu sistema directamente al cerebro del agente, permitiendo una comunicación fluida y bidireccional.

Capas de Seguridad

Para garantizar que solo tus sistemas autorizados puedan interactuar con el agente, el canal de Webhooks ofrece dos métodos de validación configurables:

Validación por Header: Puedes definir un nombre de cabecera personalizado (ej. X-Webhook-Secret) y un valor secreto. Atendium rechazará cualquier petición que no incluya estas credenciales exactas.
Validación por Origin: Puedes especificar una lista de dominios u IPs autorizadas. El sistema validará el origen de la petición antes de procesar el mensaje.

Puedes optar por utilizar uno de los métodos o ambos en conjunto para una seguridad reforzada.

Modos de Respuesta

Dependiendo de la arquitectura de tu sistema, puedes elegir cómo recibir las respuestas del agente:

Respuesta Inmediata (Síncrona): El agente procesa el mensaje y devuelve la respuesta directamente en el cuerpo de la petición HTTP (ideal para interfaces de chat en tiempo real).
Respuesta Diferida (Callback/Asíncrona): El sistema recibe el mensaje, confirma la recepción de inmediato y envía la respuesta del agente posteriormente a una URL de Callback que tú definas. Este modo permite gestionar tiempos de procesamiento más largos o flujos de trabajo complejos.

Configuración Avanzada

Además de los parámetros técnicos, puedes gestionar el comportamiento del agente:

Personalidad (Character): Elige qué agente procesará las peticiones de este Webhook. Puedes configurar agentes con diferentes sets de herramientas (tools) para integraciones específicas.
Pausa con un Clic: Detén el procesamiento de mensajes del Webhook instantáneamente desde el dashboard, útil para mantenimientos o pruebas de integración.

Guía Técnica de Implementación

Para integrar el webhook en tu sistema, debes seguir las siguientes especificaciones técnicas de comunicación:

1. Enviar Mensaje (POST)

Debes enviar una petición POST al endpoint de tu canal con el siguiente cuerpo JSON:

{
  "content": "MENSAJE DEL USUARIO",
  "to": "ID_UNICO_DE_CONTACTO"
}

content: El texto que el usuario envía al agente.
to: Un identificador único (teléfono, ID de usuario, etc.) para mantener el hilo de la conversación.

2. Respuesta del Agente

El servidor responderá (en modo inmediato) con la siguiente estructura:

{
  "success": true,
  "response": {
    "caption": "RESPUESTA DEL AGENTE",
    "resources": [
      {
        "uri": "URL DEL RECURSO",
        "type": "resource",
        "mimeType": "image/png"
      }
    ]
  },
  "metadata": {
    "agent_id": "...",
    "channel_id": "...",
    "webhook_response_mode": "immediate"
  }
}

caption: El mensaje de texto generado por la IA.
resources: Una lista de archivos (imágenes, audios, documentos) que el agente quiera enviar.
metadata: Información de contexto sobre la sesión y el canal.

[!TIP] Si utilizas el Modo Diferido (Callback), tu servidor de callback recibirá este mismo objeto JSON mediante una petición POST.

[!NOTE] Esta herramienta está pensada para que desarrolladores de software puedan expandir el alcance de los sistemas que están creando o insertar el agente AI de forma transparente dentro de sus propios ecosistemas digitales.

Para detalles sobre el formato JSON de los payloads, consulta la Documentación Técnica de la API.