Enviar mensajes

El endpoint de chat es el corazón de la API: envías el mensaje de un usuario y recibes la respuesta del bot, generada sobre tu propia base de conocimiento (RAG). Junto a la respuesta te devolvemos las fuentes en las que se apoyó y las métricas de la consulta.

Autenticación

Todas las peticiones se autentican con tu API key pública en la cabecera X-API-Key. Cada endpoint está acotado a tu cuenta: solo operas sobre tus propios bots y conversaciones. Genera y gestiona tus claves desde el panel de BotDesk, en Ajustes → API.

Enviar un mensaje

Ruta base: /v1/public/v1/chat

Método	Ruta	Propósito
POST	/chat	Enviar un mensaje y recibir la respuesta del bot con sus fuentes.

Parámetros del cuerpo

Campo	Tipo	Requerido	Descripción
message	string	Sí	El mensaje del usuario. Máximo 2000 caracteres.
conversation_id	UUID	No	Continúa una conversación existente. Omítelo para empezar una nueva.
user_ref	string	No	Tu propia referencia del usuario final (email, id, teléfono). Máximo 100 caracteres.

Petición

POST /v1/public/v1/chat
X-API-Key: <tu-api-key>
Content-Type: application/json

{
  "message": "¿Cuál es el horario de atención?",
  "user_ref": "cliente@example.com"
}

Respuesta (200 OK)

{
  "conversation_id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f",
  "response": "Atendemos de lunes a viernes de 9 a 18h.",
  "sources": [{ "filename": "horarios.pdf", "score": 0.94 }],
  "tokens_used": 312,
  "latency_ms": 840
}

Campo	Tipo	Descripción
conversation_id	UUID	La conversación a la que pertenece esta respuesta. Reutilízalo para continuar el hilo.
response	string	La respuesta del bot, fundamentada en tu base de conocimiento.
sources	lista	Fragmentos de conocimiento que respaldan la respuesta, cada uno con filename y un score de relevancia (0–1).
tokens_used	entero	Tokens consumidos al generar la respuesta.
latency_ms	entero	Tiempo de procesamiento del servidor, en milisegundos.

Continuar una conversación

Si no envías conversation_id, se crea una conversación nueva y su id llega en la respuesta. Guarda ese id y pásalo en la siguiente petición para que el bot mantenga el contexto del hilo:

{
  "message": "¿Y los fines de semana?",
  "conversation_id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f"
}

El campo user_ref es tu identificador del usuario final: úsalo para reconciliar las conversaciones con tu propio sistema. Si lo omites, se genera uno automático.

Errores

Código	Significado
401	Falta la cabecera X-API-Key o la clave no es válida.
403	Tu plan no incluye acceso a la API pública.
404	El conversation_id no existe o no pertenece a tu cuenta.
422	El cuerpo no es válido (por ejemplo, message vacío o supera los 2000 caracteres).