WeirdBot API - Documentación

Documentación

Flujos del Chatbot

Diagrama interactivo de todos los flujos conversacionales y estados del sistema

Configuración de APIs

Guía completa de todos los campos para integrar APIs externas

Configuración MySQL

Documentación de Hybrid Search y conexión a bases de datos

Endpoints Principales

GET Health Check

/health

Verifica el estado del servicio.

curl https://model.apconecta.com/health

POST Chatbot RAG

/v1/chatbot

Endpoint principal del chatbot conversacional con RAG y búsqueda híbrida.

Parámetros Requeridos:

query string REQUERIDO

Pregunta o consulta del usuario

suffix string REQUERIDO

Identificador del modelo (ej: "modelo1")

customer string REQUERIDO

Identificador del cliente

Parámetros Opcionales:

language string Opcional

Idioma: "es" o "en" (default: "es")

timezone string Opcional

Zona horaria (default: "America/Panama")

curl -X POST https://model.apconecta.com/v1/chatbot \
  -H "Authorization: Bearer TOKEN" \
  -F "query=¿Qué servicios ofrecen?" \
  -F "suffix=modelo1" \
  -F "customer=test"

POST Chatbot DB MySQL

/v1/chatbotdb

Chatbot especializado en operaciones MySQL (SELECT / INSERT / UPDATE / DELETE). Elimina 2-3 llamadas OpenAI respecto al chatbot completo porque asume que toda operación va a base de datos — sin clasificación de fuente.

Requisito previo: el sufijo debe tener database_config.json configurado (se envía en /v1/add_data).

Parámetros Requeridos:

query string REQUERIDO

Consulta del usuario sobre la base de datos

suffix string REQUERIDO

Identificador del modelo

customer string REQUERIDO

Identificador del cliente

Parámetros Opcionales:

language string Opcional

Idioma: "es" o "en" (default: "es")

timezone string Opcional

Zona horaria (default: "America/Panama")

curl -X POST https://model.apconecta.com/v1/chatbotdb \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Busca las facturas de Angel Hidalgo" \
  -F "suffix=chatbotdb" \
  -F "customer=test"

POST Analizar Conversación

/v1/analyze_conversation

Analiza el historial de conversación y el estado de un cliente para determinar si se debe enviar un mensaje proactivo. No genera respuesta para el usuario — retorna un análisis interno. Útil para automatizaciones y reportes.

Parámetros Requeridos:

suffix string REQUERIDO

Identificador del modelo

customer string REQUERIDO

Identificador del cliente a analizar

Parámetros Opcionales:

language string Opcional

Idioma: "es" o "en" (default: "es")

temperature float Opcional

Temperatura OpenAI entre 0.0 y 2.0 (default: 0.7)

timezone string Opcional

Zona horaria (default: "America/Panama")

curl -X POST https://model.apconecta.com/v1/analyze_conversation \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=modelo1" \
  -F "customer=test"

POST Configurar SQL Chat Text-to-SQL

/v1/sql_config

Configura la conexión MySQL para el servicio Text-to-SQL conversacional (/v1/sql_chat). No requiere archivos ni FAISS — solo guarda la configuración de base de datos y las reglas de negocio opcionales. Úsalo cuando el caso de uso es únicamente consultar datos tabulares, sin documentación semántica.

Parámetros Requeridos:

suffix string REQUERIDO

Identificador del modelo

database_config json REQUERIDO

Configuración MySQL: host, username, password, database, port (default 3306), allowed_tables (ver docs)

Parámetros Opcionales:

b_template string Opcional

Reglas de negocio para generación de SQL (ej: "La tabla clientes usa el campo id_cliente como PK")

curl -X POST https://model.apconecta.com/v1/sql_config \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=reportes" \
  -F 'database_config={"host":"db.empresa.com","username":"reader","password":"pass","database":"ventas_db","allowed_tables":["facturas","clientes"]}'

POST SQL Chat Text-to-SQL

/v1/sql_chat

Chatbot Text-to-SQL puro — convierte lenguaje natural en consultas SELECT y devuelve los datos con una respuesta conversacional. Mantiene historial multi-turno por session_id. No usa FAISS ni vectorstore. Requiere haber configurado la BD con /v1/sql_config previamente.

Solo consultas SELECT. INSERT / UPDATE / DELETE son bloqueados por seguridad.

Parámetros Requeridos:

query string REQUERIDO

Pregunta en lenguaje natural sobre los datos

suffix string REQUERIDO

Identificador del modelo (debe tener BD configurada con /v1/sql_config)

session_id string REQUERIDO

ID de sesión para mantener contexto entre turnos (ej: ID de usuario o conversación)

Parámetros Opcionales:

language string Opcional

Idioma de la respuesta: "es" o "en" (default: "es")

Respuesta:

{
  "success": true,
  "answer": "El cliente Juan García tuvo 3 facturas por $15,000 en enero.",
  "sql": "SELECT * FROM facturas WHERE cliente = 'Juan García' AND mes = 1",
  "data": [{ "id": 1, "monto": 5000 }, ...],
  "rows_count": 3,
  "columns": ["id", "monto", "fecha"],
  "session_id": "user_123"
}

curl -X POST https://model.apconecta.com/v1/sql_chat \
  -H "Authorization: Bearer TOKEN" \
  -F "query=Muéstrame las facturas de enero de Juan García" \
  -F "suffix=reportes" \
  -F "session_id=user_123"

DELETE Borrar Historial SQL Chat

/v1/sql_chat/history

Elimina el historial de una sesión de /v1/sql_chat. Útil para iniciar una conversación desde cero sin contexto previo.

Parámetros Requeridos:

suffix string REQUERIDO

Identificador del modelo

session_id string REQUERIDO

ID de sesión a eliminar

curl -X DELETE https://model.apconecta.com/v1/sql_chat/history \
  -H "Authorization: Bearer TOKEN" \
  -F "suffix=reportes" \
  -F "session_id=user_123"

POST Agregar Datos

/v1/add_data

Carga documentos y configuraciones para el chatbot.

suffix string REQUERIDO

Identificador del modelo

files file[] Opcional

Archivos (pdf, docx, txt, csv, json, md, html, xml, xlsx)

database_config json Opcional

Configuración MySQL (ver docs)

apis_config json Opcional

Configuración de APIs externas (ver docs)

Características

RAG con FAISS

Búsqueda semántica en documentos estáticos con embeddings de OpenAI

Hybrid Search

Text-to-SQL con GPT-4o para consultas MySQL en tiempo real

API Integration

Sistema genérico para llamadas automáticas a APIs externas