Saltar al contenido principal

Mensajes con Chatbot

La API de Neoagent te permite generar una respuesta de IA basada en la pregunta del usuario enviando una solicitud POST al endpoint /chat/Chat/ClientAsk.

Tiempo de lectura

~5-6 minutos

Endpoint​

URL de la Solicitud: https://app.neoagent.co/chat/Chat/ClientAsk
Método: POST

Headers requeridos​

La solicitud API debe incluir los siguientes encabezados:

  • Authorization: <Your-Secret-Key> - cadena, obligatorio - La clave secreta para autenticar la solicitud API
  • Content-Type: application/json - cadena, obligatorio - El tipo de contenido del payload de la solicitud

Cuerpo de la Solicitud​

El cuerpo de la solicitud debe contener los siguientes parámetros:

{
  // integer, obligatorio - El ID de sesión obtenido de la API Crear Sesión de Chat
  "sessionID": 123,
  // string, obligatorio - La pregunta o mensaje del usuario. Si chatAskType es [Image,Audio,Video], content puede estar vacío.
  "content": "hello",
  // string, opcional - Los valores opcionales son: Text, Audio, Image, Video. Este campo puede dejarse nulo, con el valor predeterminado Text.
  "chatAskType": null,
  // boolean, opcional - Si transmitir en streaming los progresos parciales. Predeterminado false.
  "stream": false,
  // List(integer), opcional - Es un array de enteros, válido solo cuando chatAskType está configurado en [Image,Video,Audio]. En modo imagen se admiten múltiples imágenes, mientras que en modo [video,Audio] se permite solo un único [video,audio].
  "fileIds": null
}

Parámetros​

  • sessionID - integer, obligatorio - El ID de sesión obtenido de la API Crear Sesión de Chat
  • content - string, obligatorio - La pregunta o mensaje del usuario. Si chatAskType es [Image,Audio,Video], content puede estar vacío
  • stream - boolean, opcional - Si transmitir en streaming los progresos parciales. Predeterminado false
  • chatAskType - string, opcional - Los valores opcionales son: Text, Audio, Image, Video. Predeterminado Text
  • fileIds - List(integer), opcional - Es un array de enteros, válido solo cuando chatAskType está configurado en [Image,Video,Audio]. En modo imagen, se admiten múltiples imágenes, mientras que en modo [video,Audio], se permite un solo [video,audio]. El audio solo se admite en formato WAV. El video se admite solo en formato [MP4,MKV,AVI,FLV,MPEG]. La imagen se admite solo en formato [PNG (.png),JPEG (.jpeg y .jpg),WEBP (.webp),GIF no animada (.gif)]. Límites de tamaño: hasta 20 MB por imagen; hasta 100 MB por video;

Soporte de Archivos Multimedia​

Cuando chatAskType está configurado en contenidos multimedia:

Formatos Admitidos:

  • Imágenes: PNG, JPEG, WEBP, GIF (no animadas)
  • Video: MP4, MKV, AVI, FLV, MPEG
  • Audio: WAV

Límites de Tamaño:

  • Imágenes: Hasta 20MB por imagen
  • Video: Hasta 100MB por video
  • Audio: Límite estándar

Reglas:

  • Imágenes: Soporta archivos múltiples
  • Video/Audio: Solo un único archivo por solicitud

Ejemplos de Solicitud​

const res = await fetch('https://app.neoagent.co/chat/Chat/ClientAsk', {
  method: 'POST',
  headers: {
    "Authorization": "<Your-Secret-Key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "sessionID": 123,
    "content": "hello",
    "stream": false
  })
});

const data = await res.json();
console.log(data);

Ejemplo con Imagen​

// Primero carga la imagen usando la API de carga de archivos
const uploadResponse = await uploadFile(imageFile);
const fileId = uploadResponse.Data.fileId;

// Luego envía la solicitud con la imagen
const res = await fetch('https://app.neoagent.co/chat/Chat/ClientAsk', {
  method: 'POST',
  headers: {
    "Authorization": "<Your-Secret-Key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "sessionID": 123,
    "content": "Analiza esta imagen",
    "chatAskType": "Image",
    "fileIds": [fileId]
  })
});

Respuesta​

Formato Estándar (sin streaming)​

La respuesta de la API será un objeto JSON con la siguiente estructura:

{
  "Data": {
    "messageid": 375561,
    "content": "¡Hola! ¿Cómo puedo asistirte hoy?",
    "totalToken": 4337,
    "noAnswer": false
  },
  // string - Versión de la API
  "Version": "1.0.0",
  // boolean - Estado de éxito de la operación
  "Success": true,
  // integer - Código de estado HTTP
  "Code": 200,
  // string - Mensaje de error si lo hay
  "Message": ""
}

Campos de la Respuesta:

  • messageid - ID único del mensaje de respuesta
  • content - El contenido de la respuesta generada por la IA
  • totalToken - Número de tokens utilizados para generar la respuesta
  • noAnswer - Indica si la IA no logró proporcionar una respuesta

Formato Streaming​

Cuando stream: true, la respuesta será en formato Server-Sent Events:

Encabezado de la Respuesta:

Content-Type: text/event-stream

Cuerpo de la Respuesta:

// Partes incrementales de la respuesta
{"content":"\n"}
{"content":"¡Hola"}
{"content":"!"}
{"content":" ¿Cómo"}
{"content":" puedo"}
{"content":" asistirte"}
{"content":" hoy"}
{"content":"?"}

// Mensaje final con metadatos
{"QuestionID":10495005,"AnswerID":10495006,"Answer":"\n¡Hola! ¿Cómo puedo asistirte?","TotalToken":4994}

Ventajas del Streaming:

  • ✅ Respuesta en tiempo real
  • ✅ Mejor experiencia de usuario para respuestas largas
  • ✅ Posibilidad de mostrar progresos

Manejo de Errores​

Si la solicitud falla, debes:

  1. Verificar el código de estado HTTP para errores a nivel de red
  2. Examinar los campos Code y Message en la respuesta para errores a nivel de negocio
  3. El campo Message contendrá información detallada sobre el error

Posibles Errores​

CódigoDescripción
400Parámetros faltantes o no válidos
401Clave API no válida
404Sesión no encontrada
429Límite de tasa superado
500Error interno del servidor

Ejemplo de Respuesta con Error​

{
  "Data": null,
  "Version": "1.0.0",
  "Success": false,
  "Code": 404,
  "Message": "Sesión no encontrada"
}