🧠 Token Permanente para WhatsApp Business Guía paso a paso — Meta Cloud API

🎯 Objetivo: Configurar un Token Permanente para la API de WhatsApp Business, eliminando la necesidad de renovarlo cada 24 horas.

📘 Glosario de conceptos

⚖️ Comparativa: Token Temporal vs Permanente

Aspecto Token Temporal Token Permanente
Duración 24 horas Indefinido / 60+ días
Dónde se genera WhatsApp → Configuración Business Settings → Usuarios del sistema
Permisos Automáticos (heredados) Selección manual obligatoria
Renovación Cada 24 horas No necesita renovación
Uso recomendado Pruebas rápidas ✅ Producción

📋 Prerrequisitos

💡 Nota: Si no tienes cuenta Business, créala gratuitamente en el enlace anterior.

1 Acceder a Business Settings

¿Por qué? Los tokens permanentes no se generan desde el panel de WhatsApp, sino desde Business Settings → Usuarios del sistema.

  1. Ve a business.facebook.com/settings/
  2. Inicia sesión con tu cuenta de Meta.
  3. En el menú izquierdo, busca Usuarios del sistema (System Users).

⚠️ Si no ves esta opción, tu cuenta puede no tener permisos de administrador.

2 Crear un Usuario del Sistema

  1. En Usuarios del sistema, haz clic en "Agregar" (Add).
  2. Completa los campos:
    • Nombre: agente_restaurante_bot (o el que prefieras)
    • Rol: Admin
  3. Haz clic en "Crear" (Create).

✅ El usuario aparecerá en la lista con un identificador numérico.

3 Asignar permisos al usuario

❕ Importante: Sin estos permisos, el token no funcionará.

  1. En la lista de usuarios, haz clic en el que creaste.
  2. Ve a la sección "Activos asignados" o "Apps instaladas".
  3. Haz clic en "Agregar" (Add).
  4. Selecciona tu app (ej: agente_Restaurante).
  5. Haz clic en "Guardar".

✅ Verifica que la app aparezca con "Acceso total".

4 Generar el token permanente

⛔ PASO CRÍTICO: Si te equivocas aquí, el token no funcionará.

  1. En la página del usuario del sistema, haz clic en "Generar token".
  2. Seleccionar app: elige agente_Restaurante. → "Siguiente".
  3. Definir caducidad:
    • ✅ "Nunca" (Never) → si está disponible.
    • ⚠️ Si no, selecciona "60 días" (la opción más larga).
  4. Asignar permisos — ⚠️ OBLIGATORIOS:
    • ☑️ whatsapp_business_management
    • ☑️ whatsapp_business_messaging ← ¡EL QUE MÁS FALTA!
    • ☑️ whatsapp_business_profile
    • ☑️ manage_app_solution (opcional pero recomendado)
  5. Haz clic en "Generar token" (o "Continuar").
  6. ¡COPIA EL TOKEN COMPLETO! (comienza con EAA...). Guárdalo en un lugar seguro.

❌ Error común: Si whatsapp_business_messaging no aparece, significa que tu app no tiene el caso de uso de WhatsApp activado. Debes activarlo en Meta Developers → Casos de uso → Conectar en WhatsApp.

5 Actualizar el archivo .env

Ejecuta en la terminal:

nano ~/proyectos/agente_restaurante/.env

Agrega o actualiza estas líneas (con tus valores reales):

WHATSAPP_TOKEN=EL_TOKEN_PERMANENTE_QUE_COPIASTE
PHONE_NUMBER_ID=1141863539007752
BUSINESS_ACCOUNT_ID=865292805902279

Guardar y salir: Ctrl+O → Enter → Ctrl+X

6 Verificar el token

Prueba el token con curl:

$ curl -X GET "https://graph.facebook.com/v18.0/me?access_token=EL_TOKEN_AQUI"
{"id":"1029103326308917","name":"agente_Restaurante"}

Prueba el Phone Number ID:

$ curl -X GET "https://graph.facebook.com/v18.0/1141863539007752?access_token=EL_TOKEN_AQUI"
{"id":"1141863539007752","display_phone_number":"+1 555 646 5740"}

✅ Si ves estos resultados, el token es válido.

7 Reiniciar el servidor

# Detener el servidor (Ctrl+C)
$ cd ~/proyectos/agente_restaurante
$ export PYTHONPATH=$PWD
$ source venv/bin/activate
$ uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

8 Iniciar servicios y prueba final

8.1 Iniciar Ollama

$ ollama serve &
$ sleep 3
$ curl http://localhost:11434
Ollama is running

8.2 Iniciar ngrok

# En una NUEVA terminal
$ ngrok http 8000
Forwarding https://nucleus-carried-natural.ngrok-free.dev -> http://localhost:8000

⚠️ Importante: La URL de ngrok cambia cada vez que lo inicias. Si cambia, debes actualizarla en Meta Developers.

8.3 Verificar FastAPI

$ curl http://localhost:8000/health
{"status":"healthy","model":"qwen:7b","database":"sqlite"}

8.4 Verificar webhook en Meta

  1. Ve a Meta Developers
  2. Selecciona tu app → WhatsApp → Configuración
  3. Verifica que la Callback URL sea: https://[tu-url-ngrok]/webhook
  4. Si cambió, actualízala y haz clic en "Verificar y guardar".

8.5 Enviar mensaje desde WhatsApp

Envía este mensaje desde WhatsApp:

muéstrame el menú

8.6 Monitorear logs

En la terminal de FastAPI:

INFO: Procesando mensaje de ***4567: muéstrame el menú
INFO: Respuesta generada para ***4567 (1234 chars)
INFO: Mensaje enviado a ***4567
INFO: POST /webhook HTTP/1.1" 200 OK

8.7 Verificar respuesta en WhatsApp

Debes recibir el menú completo:

📋 *Nuestro menú:*

*BEBIDAS*
• Agua: $3,000
• Café: $4,000
• Chocolate: $4,000
• Gaseosa: $4,000
• Jugo natural: $5,000

*CARTA*
• Bandeja Paisa Completa: $28,000
• Berenjena a la parmesana: $18,000
• Chuleta Valluna: $20,000
• Mojarra Frita: $26,000
• Sancocho de Gallina: $22,000

*DESAYUNOS*
• Calentado Valluno: $12,000
• Changua con Pan: $10,000
• Huevos Pericos: $11,000
• Tamales Vallunos: $14,000

*ESPECIALES*
• Ajiaco: $17,000
• Arroz con Pollo: $16,000
• Bandeja Paisa: $22,000
• Frijolada: $25,000
• Lechona Tolimense: $19,000
• Mondongo: $20,000
• Sancocho de Gallina: $18,000

*MENU_DIA*
• Menú del día - Carne: $15,000
• Menú del día - Cerdo: $15,000
• Menú del día - Pescado: $15,000
• Menú del día - Pollo: $15,000
• Menú del día - Vegetariano: $15,000

¿Te gustaría pedir algo o necesitas más información? 😊

⚠️ Errores comunes y soluciones

Error Causa Solución
Session has expired Token temporal expirado Generar token permanente siguiendo esta guía
The access token could not be decrypted Token mal copiado o inválido Volver a generar y copiar completo
The access token could not be decrypted + 190 Falta permiso whatsapp_business_messaging Seleccionar el permiso en el Paso 4.4
El permiso whatsapp_business_messaging no aparece App sin caso de uso de WhatsApp Activar "Conectar en WhatsApp" en Meta Developers → Casos de uso
curl: (7) Failed to connect Ollama o ngrok no están corriendo Iniciar servicios (Paso 8.1 y 8.2)

✅ Resumen final

Elementos configurados correctamente:

🎉 ¡El sistema está listo para producción!

📚 Guía elaborada con enfoque tutor — explicación clara, paso a paso.
Proyecto: agente_Restaurante — "El Sazón del Boulevard"