Docs / Ayuda · Solución de problemas

Solución de problemas

Cuando algo no cuadra, casi siempre es una de seis cosas: la licencia, la conexión con Cloudflare, un canal caído, una versión vieja, respuestas flojas del bot, o que estás corriendo el comando en la carpeta equivocada. Esta página va directo a cada una — y al final te decimos dónde pedir ayuda humana.

Primero: corre el diagnóstico

Antes de adivinar, corre forjabot doctor. Revisa tu bot de arriba abajo y te dice con ✓ / ⚠ / ✗ qué está bien y qué no. No cambia nada — solo mira y reporta, así que es seguro correrlo cuantas veces quieras.

# diagnóstico general — no toca nada, solo revisa
$ npx forjabot doctor
✓ carpeta del bot detectada · giro: barbería
✓ wrangler.toml · package.json · node_modules
✓ member/config.local.ts
✓ licencia válida · plan pro
⚠ hay una versión nueva (1.2.0 → 1.4.0)
✓ el bot responde en línea
1 aviso · todo lo demás, en orden

Esto es lo que revisa, y qué significa cuando algo aparece con ⚠ o ✗:

Problemas comunes

1 · «Licencia inválida o expirada»

Tu licencia controla si puedes instalar y actualizar bots del catálogo — no controla el bot que ya está corriendo. Tu bot vive en tu propia cuenta de Cloudflare, así que aunque la licencia caduque, el bot NO se apaga: sigue atendiendo a tus clientes con normalidad. Lo único que se bloquea es bajar nuevas plantillas o traer actualizaciones.

Para arreglarla: revalida corriendo forjabot doctor de nuevo, revisa que la key esté guardada en ~/.forja/config.json, o vuelve a pasarla directo con --key.

# revalida pasando tu licencia directamente
$ npx forjabot doctor --key HZN-XXXX-XXXX-XXXX
✓ licencia válida · plan pro

2 · «wrangler no conectado» / error de auth de Cloudflare

Cloudflare es la nube donde vive tu bot, y wrangler es la herramienta que despliega ahí. Si al publicar ves un error de autenticación o de sesión, casi siempre es que tu sesión de Cloudflare caducó. Se arregla reconectando la cuenta — abre tu navegador para que autorices.

# reconecta tu cuenta de Cloudflare (abre el navegador)
$ pnpm wrangler login
✓ sesión iniciada correctamente

Cuando termines, vuelve a desplegar con pnpm deploy (o pídele a tu agente que publique el bot).

3 · El bot no responde en un canal

Que el bot funcione en Telegram pero no en WhatsApp, o al revés, casi nunca es un problema del bot en sí — es de la conexión de ese canal. Revisa en este orden:

1. El panel de conexiones

   Abre /admin/conexiones en tu panel. Cada canal tiene un badge: verde = conectado, gris = sin conectar. Si está gris, ahí está el culpable.

2. Los secretos del canal

   Cada canal necesita sus llaves (token de Telegram, credenciales de Twilio para WhatsApp, etc.). Si faltan o quedaron mal, el canal no recibe mensajes. Se guardan como secretos, nunca en el chat.

3. La ventana de 24 horas de WhatsApp

   WhatsApp solo deja responder libremente a quien te escribió en las últimas ~24 h. Fuera de esa ventana hace falta una plantilla aprobada. Si «solo a veces no contesta» en WhatsApp, suele ser esto — no una falla.

4 · «Tengo una versión vieja»

Si doctor te avisa que hay una versión más nueva, traes las mejoras y correcciones con forjabot update. Actualiza el código de la plantilla conservando intacta tu configuración: tu member/config.local.ts, tu base de conocimiento y tus llaves no se tocan.

$ npx forjabot update
↗ versión nueva: 1.2.0 → 1.4.0
✓ actualizado · tu configuración quedó intacta
# para publicar el cambio: reinstala e implementa
$ pnpm install && pnpm deploy

Actualizar no publica por sí solo: el cambio queda en tu carpeta hasta que reinstales dependencias y despliegues. Tu agente puede hacer los dos pasos por ti.

5 · El bot contesta mal o le falta información

Si responde con datos viejos, inventa cosas o suena fuera de tono, no es un error técnico: es que le falta contexto o ajuste. Para esto no abres la terminal — se lo pides a tu agente en español y él edita la base de conocimiento, el tono o las instrucciones del bot.

Ejemplos de lo que le puedes decir: «el bot no sabe nuestros horarios nuevos, afínalo», «contestó cortante a un cliente, ajústale el tono» o «hazle mantenimiento antes de fin de mes». Recuerda que los cambios de comportamiento tampoco están en vivo hasta que se despliega el bot.

6 · «No encuentro mi bot»

Los comandos update y doctor buscan tu bot por un marcador (.horizontes-bot.json) en la carpeta actual y sus subcarpetas. Si lo corres desde otro lado, no lo encuentra. La solución: entra a la carpeta del bot antes de correr el comando, o pásale la ruta directamente.

# opción A — entra a la carpeta del bot y corre el comando ahí
$ cd ~/mis-bots/barberia
$ npx forjabot doctor
# opción B — pásale la ruta directo
$ npx forjabot doctor ~/mis-bots/barberia