Contenido del curso

Avances y Personalización

Webhook de WhatsApp con Express y dotenv

Resumen

Conectar un bot de WhatsApp con tu propio servidor empieza por un paso clave: configurar el webhook de WhatsApp API usando Express, dotenv y port forwarding. Aquí verás cómo armar ese flujo desde el código de ejemplo de Meta hasta recibir el primer mensaje replicado en tu chat, ideal si estás construyendo un bot conversacional como MedPet.

Qué hace el código base de Meta para el webhook

Meta entrega un proyecto de ejemplo en su documentación que sirve como punto de partida para levantar el servidor. Ese código trae todo lo necesario para validar la conexión y enviar un mensaje de eco.

El ejemplo usa tres piezas que conviene reconocer desde el inicio:

  • Express como framework del servidor.
  • Axios para hacer la petición a la API de WhatsApp.
  • dotenv para manejar variables de entorno sensibles.

La lógica del eco es simple: cada mensaje que llega al bot se replica con el mismo texto. Eso te permite confirmar que la comunicación entre tu servidor y la API funciona antes de meter lógica más compleja [1:30].

¿Qué es un webhook en WhatsApp API? Es un endpoint público en tu servidor que Meta usa para enviarte los mensajes entrantes. Tú lo verificas con un token secreto y, una vez validado, recibes cada evento del bot en tiempo real.

Cómo conectar el webhook con variables de entorno

Después de copiar el código de ejemplo en un archivo server.js, el siguiente paso es sacar los valores sensibles del código y moverlos a un archivo .env. Esto evita exponer tokens en el repositorio y deja la configuración lista para escalar.

Qué variables de entorno necesita el proyecto

El archivo .env debe contener cinco variables que el servidor leerá con process.env:

  • WEBHOOK_VERIFY_TOKEN: una palabra secreta que tú defines, por ejemplo platzi.
  • API_TOKEN: el access token que genera Meta en el panel de desarrolladores.
  • BUSINESS_PHONE: el identificador del número de teléfono de tu app.
  • API_VERSION: la versión de la API, por ejemplo v20.0.
  • PORT: el puerto local, típicamente 3000.

Agrega .env al .gitignore para no subirlo al repositorio. En su lugar, crea un .env.example con los nombres de las variables vacías para que cualquier persona del equipo sepa qué configurar [5:40].

Cómo ajustar el código de ejemplo

El ejemplo de Meta llega con la versión 18 hardcodeada y nombres como businessPhoneNumberId. Conviene reemplazar esos valores por las variables del .env para tener control desde un solo lugar. Lo mismo aplica al header Authorization, que debe leer API_TOKEN, y a la URL de Axios, que toma API_VERSION y BUSINESS_PHONE dinámicamente [7:20].

Cómo levantar el servidor con nodemon y exponerlo a internet

Para que el servidor reinicie en cada cambio durante desarrollo, nodemon es la herramienta indicada. Necesita un archivo nodemon.json con su configuración:

  • watch: apunta a src para escuchar cambios.
  • ext: define las extensiones json y js.
  • ignore: excluye node_modules y carpetas como public.
  • exec: ejecuta node src/server.js.

Al correr npm start por primera vez es común ver un error porque el código usa imports modernos de JavaScript. La solución es agregar "type": "module" en el package.json y volver a ejecutar el comando [11:50].

Por qué usar port forwarding de Visual Studio Code

Un servidor en localhost:3000 no es accesible desde fuera de tu máquina, y la API de Meta necesita una URL pública para enviarte los eventos. Aquí entra el port forwarding de Visual Studio Code, que toma tu puerto local y lo expone con una URL pública vía GitHub.

El flujo es directo: en la pestaña de puertos seleccionas Forward a Port, eliges el 3000, te autenticas con GitHub y cambias la visibilidad a pública. VS Code te entrega una URL que ya puedes pegar en el panel de Meta.

¿Por qué el webhook devuelve 403 al abrirlo en el navegador? Porque el endpoint /webhook exige un token de verificación en la URL. Si entras sin token, la respuesta correcta es Forbidden: significa que la validación está activa y funcionando.

Recuerda que esta URL solo sirve en modo desarrollo. No es una solución para producción [14:30].

Cómo verificar el webhook en el panel de Meta

Con la URL pública lista, vas al panel de Meta en la sección de webhooks. Ahí pegas la URL completa terminada en /webhook y agregas el mismo verify token que pusiste en tu .env, en este caso platzi.

Al dar Verify and Save, Meta hace una petición GET a tu servidor y compara el token. Si coincide, la conexión queda establecida y aparece la pantalla para suscribirte a eventos.

Los tres eventos clave que debes activar son:

  1. Messages para recibir mensajes entrantes.
  2. Message templates para gestionar plantillas.
  3. Template quality update para monitorear el estado de las plantillas.

Qué hacer cuando el access token expira

Al enviar el primer Hola desde WhatsApp, es muy probable que aparezca un error 401 con el mensaje Session has expired. Eso pasa porque el token temporal del panel de pruebas tiene una vida corta.

La solución es regenerar el token desde API Setup, copiarlo de nuevo al .env, reiniciar el servidor con npm start y volver a enviar el mensaje. El bot debería responder con el mismo texto que enviaste, confirmando que el eco funciona [17:50].

¿Qué hago si el token de WhatsApp expira constantemente? Usa el token temporal solo para pruebas iniciales. Para un proyecto estable necesitas generar un token permanente desde la configuración de Meta Business, vinculado a un usuario de sistema.

Ahora que el flujo de eco está activo, el siguiente reto es modificar la lógica para que el mensaje no se replique como reply. ¿Cómo lo resolverías tú? Déjalo en los comentarios.