Bot Orbe

Agente de ventas con IA para WhatsApp: conversa por texto, notas de voz e imágenes, consulta el catálogo del negocio y gestiona reservas y pedidos mediante la Assistants API de OpenAI.

Parte del ecosistema Orbe

Orbe es una plataforma para PYMES que combina un chatbot de WhatsApp con IA, un dashboard web y una API central.

Repo	Rol	Acceso
bot-orbe	Agente de ventas para WhatsApp (este repo)	Público
api-orbe	API centralizada (usuarios, catálogo, reservas, pedidos)	Privado
web-orbe	Dashboard web	Público

✨ Características

• Multimodal: responde texto, transcribe notas de voz con Whisper e interpreta imágenes subiéndolas a OpenAI con propósito vision.
• Cerebro con OpenAI Assistants: hilo de conversación por usuario y function calling con herramientas de negocio (obtener_servicios, obtener_productos, ver_disponibilidad, reservar, ordenar, seguimiento, entre otras) resueltas contra la API central de Orbe.
• Voz a voz: si el cliente envía audio, la respuesta llega como nota de voz generada con ElevenLabs (eleven_turbo_v2_5) y convertida de MP3 a OPUS con ffmpeg.
• Debounce de mensajes: agrupa los mensajes consecutivos de un usuario durante 4 segundos y los procesa como uno solo.
• Presencia natural: muestra "escribiendo..." o "grabando audio..." según el tipo de respuesta.
• Respuestas ricas: detecta imágenes en formato Markdown dentro de la respuesta del asistente y las envía como media de WhatsApp.
• API HTTP integrada: envío individual (POST /v1/message/send), envío con media (POST /v1/message/sendMedia), difusión masiva con 5 variantes del mensaje generadas por IA y delay de 5 s por número (POST /v1/message/difusion) y estado de conexión (GET /v1/status).
• Telemetría hacia la API central: reporta el estado del bot (ready, require_action, auth_failure), registra el consumo de tokens por ejecución y reinicia el hilo tras completar una reserva u orden.

🛠️ Stack

• Runtime: Node.js (ES Modules)
• Framework de bot: BuilderBot 1.1.6 (@builderbot/bot) con proveedor Baileys (WhatsApp Web)
• IA: OpenAI — Assistants API, Whisper (whisper-1) y Chat Completions (gpt-3.5-turbo para variantes de difusión)
• Voz: ElevenLabs TTS + fluent-ffmpeg / ffmpeg-static
• Estado: MemoryDB de BuilderBot (la persistencia de usuarios e hilos vive en la API central de Orbe)
• Tooling: Docker multi-stage (node:21-alpine + pnpm), nodemon y ESLint

📁 Estructura del proyecto

src/
├── app.js              # Entrypoint: crea el bot, levanta el servidor HTTP y reporta estado
├── messageRoutes.js    # Endpoints REST (/v1/message/*, /v1/status)
├── api/                # Cliente axios de la API central (funciones de negocio)
├── config/             # Carga y exporta variables de entorno
├── database/           # MemoryDB de BuilderBot
├── flow/               # Flujos: welcome (texto), listen (voz), vision (imagen), assistant (IA)
├── provider/           # Proveedor Baileys (WhatsApp)
├── services/           # OpenAI (assistant, whisper, completions) y ElevenLabs (tts)
├── utils/              # Cola con debounce, presencia, usuarios, fecha/hora
├── assets/             # Imágenes recibidas
└── audio/              # Notas de voz recibidas y generadas
public/                 # Archivos estáticos

🚀 Desarrollo local

# 1. Instalar dependencias
npm install

# 2. Configurar variables de entorno
cp .env.example .env

# 3. Modo desarrollo (ESLint + nodemon)
npm run dev

# Producción
npm start

# Solo lint
npm run lint

En el primer arranque el proveedor Baileys requiere vincular una sesión de WhatsApp.

Docker

docker build --build-arg PORT=4000 -t bot-orbe .
docker run --env-file .env -p 4000:4000 bot-orbe

Variables de entorno

Variable	Descripción
PORT	Puerto del servidor HTTP del bot
URL_API	URL base de la API central de Orbe
COOKIE_ADMIN_JWT	JWT de administrador para autenticarse contra la API central
OPENAI_API_KEY	API key de OpenAI
ASSISTANT_ID	ID del Assistant de OpenAI configurado con las herramientas del negocio
ELEVENLABS_API_KEY	API key de ElevenLabs
ELEVENLABS_VOICE_ID	ID de la voz de ElevenLabs para las notas de voz

👥 Hecho por bambai-labs

Desarrollado por el equipo de bambai-labs.