Configuración del Agente IA y Webhook de Mensajes

Esta sección ayudará a los usuarios a conectar su propio agente externo a Nubot y entender cómo fluye la información hacia su webhook.

1. Activar el Webhook para tu Agente IA

Para recibir los mensajes que llegan a través de Nubot en tu propia IA, debes configurar un webhook personalizado. Sigue estos pasos:

Si ya creaste un Agente IA:

1. Ingresa a tu cuenta en la plataforma de Nubot.

2. Ve al módulo Agentes IA y selecciona el agente que deseas configurar.

3. Dentro de la configuración del agente, ubica la opción Chatbot Externo (URL Personalizada).

4. Activa esta opción.

5. Introduce la URL de tu webhook (la URL de tu agente externo que recibirá los mensajes).

6. Guarda los cambios.

Si aún no tienes un Agente IA creado:

1. Ingresa a la plataforma y ve a Agentes IA.

2. Haz clic en Crear Agente IA.

3. Ingresa un nombre y una descripción.

4. Haz clic en Crear.

5. Serás redirigido automáticamente a la configuración de tu nuevo agente.

6. Activa la opción Chatbot Externo (URL Personalizada).

7. Introduce la URL de tu agente externo (webhook).

8. Guarda los cambios.

⚠ Aviso: Al webhook solo le llegaran mensajes si el ticket (conversacion abierta entre el cliente final y nubot) esta asignado al agente IA que se configuro

---

2. Formato del mensaje recibido en el Webhook

Cuando un usuario final interactúe a través de uno de tus canales conectados (WhatsApp Business, Gupshup, Messenger, Instagram, etc.), Nubot enviará al webhook configurado un JSON con el siguiente formato (el formato es fijo y no se puede modificar):

Campo principal	Tipo	Descripción
configuration	Objeto	Configuración del chatbot que ejecutará la respuesta. Incluye parámetros de personalización y comportamiento.
messages	Array	Historial de mensajes de la conversación previa. Se recomienda usarlo para contexto.
metadata	Objeto	Datos de sesión y canal del usuario que escribió el mensaje.
nubot_metadata	Objeto	Información estructurada adicional: equipos, embudos, ticket y contexto de negocio.

1. Detalle de configuration

Campo	Tipo	Descripción
business_case	String	ID del chatbot (referencia a qué lógica debe usar).
prompt_params	Objeto	Parámetros adicionales para el prompt del agente (puede variar según la lógica).

---

2. Detalle de messages

Campo sugerido (por entrada)	Tipo	Descripción
type	String	Rol del hablante: user, assistant, system.
content	String	Texto del mensaje.
caption(opcional)	String	Texto descriptivo de la imagen
media_url (opcional)	String	url del archivo del mensaje (imagen, video, archivo)
mime_type (opcional)	String	Indica el tipo archivo que se recibio
created_message (opcional)	Timestamp	Fecha y hora del mensaje.

Ejemplo:

[
    {
      "type": "text",
      "content": "Hola, este es un mensaje de prueba queee",
      "created_message": "2025-06-06T22:38:25.918342+00:00"
    },    
    {
      "type": "image",
      "caption": "",
      "created_message": "2025-06-09T19:48:56.406271+00:00",
      "media_url": "https://storage.googleapis.com/dev-aichain-storage-pub/bFh4JzE98KSETiOcZxPgtOgbDP93/4c17ac06-3466-422d-a30d-94e1324cac26.jpg",
      "mime_type": "image/jpeg"
    }
]

---

3. Detalle de metadata

Campo	Tipo	Descripción
userId	String	ID temporal o real del usuario.
channelType	String	Canal por el que se recibió el mensaje (ej: whatsapp_business).

---

4. Detalle de nubot_metadata

Campo	Tipo	Descripción
organization_id	String (UUID)	ID de la organización en Nubot.
async_response	Boolean	Si se espera una respuesta asíncrona (true) o inmediata (false).
ticket_id	String (UUID)	ID del ticket en proceso. Puede ser null si no hay ticket.

JSON de ejemplo:

{
  "configuration": {
    "business_case": "chatbot_id",
    "prompt_params": { /* parámetros definidos por el chatbot */ },
  },
  "messages": [
    {
      "content": "Hola",
      "type": "text",
      "created_message": "2025-06-09T19:40:49.956846+00:00"
    },
    {
      "content": "Que",
      "type": "text",
      "created_message": "2025-06-09T19:40:50.648974+00:00"
    },
    {
      "content": "Tal",
      "type": "text",
      "created_message": "2025-06-09T19:40:51.511026+00:00"
    },
  ],
  "metadata": {
    "userId": "temp_user_id",
    "channelType": "whatsapp_business",
  },
  "nubot_metadata": {
    "organization_id": "org_id",
    "async_response": true,
    "ticket_id": "ticket_id",
  }
}

Nota: El campo messages contiene el grupo de mensajes enviado por el cliente, en un intervalo de tiempo corto

---

3. Consideraciones

• Puedes asociar más de un agente IA por cuenta.

• El formato del mensaje es establecido por Nubot y no puede ser modificado.

• Tu endpoint debe responder con un código HTTP 202 Accepted para confirmar que recibió el mensaje correctamente. Si no lo hace, Nubot puede interpretar que el webhook falló.

---

4. Requisitos del Webhook

• El endpoint debe aceptar peticiones HTTP POST con cuerpo JSON.

• Debe responder con un código HTTP 202 (Accepted). Cualquier otro código podría ser interpretado como un fallo.