Waai

Documentación

Todo lo que necesitas para poner tu propio asistente de WhatsApp en producción.

Introducción

Waai es una plantilla de bot de WhatsApp lista para producción: responde preguntas frecuentes con la información real de tu negocio, detecta intención de compra y manda tu enlace de acción, y deriva a un humano cuando no sabe algo. Corre sobre la API oficial de WhatsApp Cloud de Meta — nunca sobre librerías no oficiales — así que no hay riesgo de que baneen tu número.

Está pensado para vivir en tu propio servidor: Python + FastAPI + SQLite, sin Docker obligatorio, sin base de datos externa. El código es abierto (MIT) en github.com/2stdg/waai.

Antes de empezar

  1. Un servidor propio con Ubuntu, nginx y certbot, con un dominio o subdominio apuntando a su IP pública.
  2. Un número de teléfono real dedicado a WhatsApp Business (no puede tener WhatsApp normal activo al mismo tiempo).
  3. Una app de Meta for Developers (tipo “Business”) con el producto WhatsApp agregado.
¿Vas a tener más de un bot bajo el mismo negocio? Considera verificar tu negocio ante Meta desde el principio — sin verificación, Meta limita cuántas cuentas de WhatsApp Business puede crear un mismo Business Portfolio.

¿Dónde consigo el servidor?

No necesitas nada caro para empezar — dos opciones con capa gratuita real:

ProveedorQué ofrece gratis
AWS Free TierHasta 200 USD en créditos (100 al registrarte + 100 más explorando servicios), válidos 6 meses. Alcanza de sobra para correr Waai mientras pruebas.
Oracle Cloud “Always Free”Capa gratuita permanente (sin fecha de expiración) — incluye cómputo ARM Ampere A1 (varios núcleos y RAM, suficiente para un bot ligero como este) además de almacenamiento y base de datos gratis. Buena opción si quieres evitar que algo expire después de unos meses.

Configura tu app de Meta

  1. Crea la app en developers.facebook.com, agrega el producto WhatsApp.
  2. Registra tu número real: API Setup → Add phone number → verificación por SMS/llamada.
  3. Si te da un error de “Unverified WABA” al registrar el número, pasa la app a modo Live — no siempre hace falta la verificación completa del negocio.
  4. Suscribe la app a los eventos de tu WABA (POST /{waba_id}/subscribed_apps).
  5. Crea un System User (Meta Business Suite → Configuración del negocio → Usuarios) con permisos whatsapp_business_management y whatsapp_business_messaging, y genera un token permanente.
  6. Publica una Privacy Policy y Terms of Service reales — Meta las pide en App settings → Basic.

Configura tus API keys

Toda la configuración vive en un solo archivo: .env en la raíz de tu proyecto. Cópialo desde .env.example y llena tus valores reales — este archivo nunca se sube a git.

VariableDónde la consigues
WHATSAPP_TOKENToken permanente del System User (paso 5 de arriba)
WHATSAPP_PHONE_NUMBER_IDApp Dashboard → WhatsApp → API Setup
WHATSAPP_VERIFY_TOKENLo inventas tú — cualquier cadena secreta, la usas también al configurar el webhook en Meta
WHATSAPP_APP_SECRETApp settings → Basic → botón “Show”. Firma cada webhook — sin esto el bot no arranca
NOTIFY_NUMBERTu número interno para avisos de escalado (nunca se comparte con el LLM)
LLM_PROVIDERanthropic u openai_compatible
ANTHROPIC_API_KEYSi usas LLM_PROVIDER=anthropic — desde console.anthropic.com
LLM_BASE_URL / LLM_MODEL / LLM_API_KEYSi usas LLM_PROVIDER=openai_compatible — sirve para Nvidia NIM, OpenRouter, Kimi, o un gateway propio como LiteLLM

Consigue una API key gratuita (Nvidia NIM)

Si no quieres pagar por un proveedor de LLM para empezar, Nvidia NIM ofrece acceso gratuito por cuota a varios modelos open source (como el que usamos en nuestros propios bots). Para conseguir tu key:

  1. Entra a build.nvidia.com/models e inicia sesión (o crea una cuenta gratis).
  2. Elige un modelo del catálogo (por ejemplo, uno de la familia Nemotron o Llama).
  3. En la página del modelo, genera tu API key — empieza con nvapi-....
  4. Úsala como LLM_API_KEY en tu .env, con:
    LLM_PROVIDER=openai_compatible
    LLM_BASE_URL=https://integrate.api.nvidia.com/v1
    LLM_MODEL= el id del modelo que elegiste (ej. nvidia/nemotron-3-super-120b-a12b)
La cuota gratuita tiene límites de uso — si tu bot crece, puedes migrar a un plan pagado de Nvidia, o combinar varios proveedores gratis/pagados a través de un gateway como LiteLLM con fallback automático entre ellos.
# .env
WHATSAPP_TOKEN=
WHATSAPP_PHONE_NUMBER_ID=
WHATSAPP_VERIFY_TOKEN=
WHATSAPP_APP_SECRET=

NOTIFY_NUMBER=

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=

# Si LLM_PROVIDER=openai_compatible, llena estos en vez de ANTHROPIC_API_KEY:
LLM_BASE_URL=
LLM_MODEL=
LLM_API_KEY=
Nunca subas tu .env a git. El .gitignore del proyecto ya lo excluye por default.

Instalación

git clone https://github.com/2stdg/waai mi-bot
cd mi-bot
cp .env.example .env         # llena tus credenciales reales
# edita config/business.yaml con los datos de tu negocio
# agrega tus archivos .md reales a knowledge/ (borra EJEMPLO.md)

sudo ./deploy/install.sh tudominio.com 8002 /opt/bots/mi-bot
# copia tu .env real a /opt/bots/mi-bot/.env
sudo systemctl enable --now mi-bot

Después, registra el webhook en Meta (dos pantallas separadas, ambas necesarias: WhatsApp → Configuration y App Dashboard → Webhooks):

  • Callback URL: https://tudominio.com/webhook
  • Verify Token: el mismo valor que pusiste en .env como WHATSAPP_VERIFY_TOKEN

Pruebas

cd /opt/bots/mi-bot
sudo -u www-data .venv/bin/python test_main.py

Costos

  • WhatsApp: gratis — el bot solo responde, nunca inicia conversación, así que se mantiene dentro del rango gratuito de la API.
  • LLM: depende del proveedor que elijas (Anthropic, o cualquiera compatible con OpenAI) — revisa su propio dashboard de facturación.
  • Servidor: el de tu cuenta en la nube — AWS y Oracle Cloud tienen capas gratuitas razonables para empezar.

Soporte

¿Prefieres que el equipo de SSTDG te ayude a implementarlo en vez de hacerlo tú mismo?

En ~1 hora de consultoría te podemos implementar tu agente. Además, recibe 50% de descuento con el código EMPRENDEDOR50.

Reservar consultoría