Este repositorio contiene un paquete completo, listo para producción, para integrar un Chatbot de Inteligencia Artificial Flotante en aplicaciones que utilicen Laravel en el backend y React (con Inertia.js y Tailwind CSS) en el frontend.
El sistema está optimizado para conectarse de manera fluida con la API de Google Gemini (usando por defecto gemini-2.5-flash) y cuenta con características avanzadas de persistencia de datos y seguridad preventiva en tiempo real.
git clone https://github.com/devpolamx/chatbot-widget-laravel-react.gitSi este proyecto te fue útil y quieres apoyar mi trabajo:
- ❤️ GitHub Sponsors: https://github.com/sponsors/devpolamx
- ☕ Invítame un café: https://www.paypal.me/poladevmx
- 💬 Widget Flotante Premium: Interfaz moderna con animaciones fluidas, indicador de escritura ("typing indicator") y modo oscuro integrado.
- 🧠 Motor de IA (Google Gemini): Conexión optimizada con la API oficial de Gemini para respuestas rápidas y contextuales.
- 🛡️ Seguridad y Prevención de Abusos: Servicio
ChatSecurityServiceintegrado que intercepta el mensaje del usuario antes de enviarlo a la API para detectar:- Intentos de Jailbreak o alteración de instrucciones del sistema.
- Intentos de extracción de datos o Inyección SQL.
- Generación de contenido restringido o pesado.
- 💾 Historial de Conversación Persistente: Los mensajes se guardan en base de datos y se limitan de forma inteligente para proveer el contexto correcto a la IA sin exceder límites de tokens.
- 📋 Auditoría de Incidencias: Registro automático de intentos de vulneración en la tabla
chat_incidenciaspara auditoría y posible baneo de usuarios malintencionados. - 📝 Renderizador de Markdown Nativo: El frontend interpreta y formatea negritas, cursivas, listas ordenadas/desordenadas y bloques de código de forma nativa sin añadir librerías externas pesadas.
El paquete está diseñado para ser copiado directamente en la estructura de directorios estándar de un proyecto Laravel + React (Inertia):
├── database/
│ └── create_chat_tables_migration.php # Migración para base de datos (mensajes e incidencias)
├── backend/
│ ├── ChatController.php # Controlador principal de la API del chat
│ ├── ChatSecurityService.php # Lógica de detección de prompt injections y abusos
│ ├── ChatMensaje.php # Modelo Eloquent para el historial de mensajes
│ └── ChatIncidencia.php # Modelo Eloquent para el registro de auditoría de seguridad
└── frontend/
└── FloatingChatWidget.tsx # Componente React (Tailwind CSS + Lucide Icons + Axios)
Asegúrate de contar con los siguientes elementos antes de comenzar con la integración:
- Backend: Laravel 10.x o superior.
- Frontend: React 18.x, Tailwind CSS v3 o superior.
- Dependencias NPM:
lucide-react,axios,@inertiajs/react. - Credenciales: Una clave de API de Google Gemini (puedes obtener una gratis en Google AI Studio).
- En tu proyecto Laravel, crea una nueva migración ejecutando:
php artisan make:migration create_chat_tables
- Abre el archivo de migración creado en
database/migrations/y reemplaza todo su contenido con el código de create_chat_tables_migration.php. - Corre la migración para crear las tablas
chat_mensajesychat_incidencias:php artisan migrate
- Copia los modelos Eloquent a tu carpeta de modelos de Laravel:
- Copia
backend/ChatMensaje.phpa app/Models/ChatMensaje.php - Copia
backend/ChatIncidencia.phpa app/Models/ChatIncidencia.php
- Copia
- Copia el servicio de seguridad a tu carpeta de servicios:
- Copia
backend/ChatSecurityService.phpa app/Services/ChatSecurityService.php (Si no tienes el directorioapp/Services, créalo).
- Copia
Añade las siguientes variables al final de tu archivo .env en la raíz de tu proyecto Laravel:
GEMINI_API_KEY="TU_CLAVE_API_DE_GEMINI"
GEMINI_API_URL="https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent"A continuación, puedes registrar estas variables de configuración en tu archivo config/services.php o crear un archivo de configuración dedicado en config/gemini.php:
// config/gemini.php
return [
'api_key' => env('GEMINI_API_KEY'),
'api_url' => env('GEMINI_API_URL', 'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent'),
];- Copia
backend/ChatController.phpa app/Http/Controllers/ChatController.php. - Modifica el espacio de nombres (
namespace) y los imports si la estructura de tu proyecto difiere del estándar.
Añade las siguientes rutas a tu archivo de rutas de Laravel (usualmente routes/web.php si utilizas Inertia, o routes/api.php si la autenticación se gestiona de otra forma):
use App\Http\Controllers\ChatController;
Route::middleware(['auth'])->group(function () {
// API del chatbot flotante
Route::get('/api/chat/history', [ChatController::class, 'getHistory'])->name('api.chat.history');
Route::post('/api/chat/preguntar', [ChatController::class, 'preguntar'])->name('api.chat.preguntar');
Route::delete('/api/chat/clear', [ChatController::class, 'clearHistory'])->name('api.chat.clear');
// Ruta de chat de pantalla completa (opcional)
Route::get('/chat', [ChatController::class, 'index'])->name('chat.index');
});Note
Por defecto, el componente frontend asume que estás usando Ziggy en Laravel para resolver rutas dinámicamente con route(). Si no utilizas Ziggy, puedes reemplazar las llamadas a route('api.chat.*') por strings estáticos (ej. "/api/chat/history") en el archivo del widget frontend.
- Instala las dependencias necesarias en tu proyecto frontend:
npm install lucide-react axios @inertiajs/react
- Copia el componente
frontend/FloatingChatWidget.tsxa tu directorio de componentes, por ejemplo enresources/js/Components/FloatingChatWidget.tsx. - Importa y renderiza el widget dentro de tu Layout principal (ej.
AuthenticatedLayout.tsxo similar) para que esté visible en todo el sistema:
import FloatingChatWidget from "@/Components/FloatingChatWidget";
export default function AuthenticatedLayout({ children }) {
return (
<div className="min-h-screen bg-gray-100 dark:bg-zinc-900">
{/* ... contenido principal de tu aplicación ... */}
<main>{children}</main>
{/* Widget del Chatbot IA */}
<FloatingChatWidget />
</div>
);
}Puedes modificar el comportamiento de la IA cambiando la constante SYSTEM_INSTRUCTION al inicio de ChatController.php:
private const SYSTEM_INSTRUCTION = <<<'INST'
Eres un Asistente Virtual experto en desarrollo web y soporte técnico.
Responde de forma clara, amigable y proporciona ejemplos de código cuando sea posible.
INST;El archivo ChatSecurityService.php contiene expresiones regulares para filtrar comportamientos. Si deseas flexibilizar o endurecer las restricciones de entrada de los usuarios, edita los arrays en dicho archivo:
$jailbreak: Para prevenir inyecciones de prompts ("olvida tus instrucciones", "actúa como...", etc.).$datosPatterns: Filtros básicos de prevención de inyección SQL y acceso a tablas internas del sistema.
El widget tiene estilos basados en Tailwind CSS y utiliza un degradado de rosa a violeta (bg-gradient-to-r from-[#D4006A] to-[#9B00A0]). Puedes adaptar fácilmente los colores editando las clases de Tailwind en FloatingChatWidget.tsx para que coincidan con la paleta de colores de tu marca.
Cada vez que un usuario ingresa una frase catalogada como sospechosa por ChatSecurityService, la aplicación realiza el siguiente flujo:
- Bloquea el envío a la API de Gemini para ahorrar tokens y proteger el sistema.
- Registra la incidencia en la tabla
chat_incidenciasalmacenando el ID del usuario, el texto ofensivo o sospechoso y el tipo de violación (jailbreak,extraccion_datos,generacion_restringida). - Retorna un mensaje de advertencia amigable al usuario en la interfaz del chat.
Esto te permite monitorear de cerca el uso del chatbot y detectar intentos maliciosos desde tu panel de administración.
Si este paquete te ha sido útil y te ha ayudado a ahorrar tiempo de desarrollo, considera apoyar su mantenimiento continuo. ¡Cualquier contribución es muy apreciada!
Si este proyecto te fue útil y quieres apoyar mi trabajo:
- ❤️ GitHub Sponsors: https://github.com/sponsors/devpolamx
- ☕ Invítame un café: https://www.paypal.me/poladevmx
Este proyecto está bajo la Licencia MIT. Siéntete libre de clonarlo, modificarlo y usarlo de manera personal o comercial. ¡Las contribuciones son bienvenidas!