{"id":542,"date":"2026-10-28T16:07:10","date_gmt":"2026-10-28T16:07:10","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/bot-whatsapp-nodejs-express\/"},"modified":"2026-10-28T16:07:20","modified_gmt":"2026-10-28T16:07:20","slug":"bot-whatsapp-nodejs-express","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/bot-whatsapp-nodejs-express\/","title":{"rendered":"Bot de WhatsApp con Node.js en la API oficial (Express, desde cero)"},"content":{"rendered":"\n

Actualizado el 28\/10\/2026<\/em><\/p>\n\n\n\n

Para crear un bot de WhatsApp con Node.js en la API oficial necesitas un servidor Express con HTTPS y dos rutas: un GET<\/code> que devuelve el desaf\u00edo de verificaci\u00f3n de Meta y un POST<\/code> que recibe los mensajes, valida la firma X-Hub-Signature-256<\/code> sobre el cuerpo crudo (con express.raw<\/code>) y responde a trav\u00e9s del endpoint \/messages<\/code> de la Cloud API usando el fetch<\/code> nativo. Sin SDK y sin m\u00e1s dependencias que Express, todo cabe en un archivo de unas 150 l\u00edneas.<\/p>\n\n\n\n

El bot final responde a “hola” o “menu” con tres botones, procesa el toque en cada bot\u00f3n, marca el mensaje como le\u00eddo, ignora eventos repetidos y corre en producci\u00f3n con Docker y HTTPS autom\u00e1tico. El c\u00f3digo se prob\u00f3 con Express 5.3 y Node.js 26, y funciona directo con Meta o a trav\u00e9s de Vectalk, cambiando solo dos variables de entorno. Si prefieres Python, el mismo bot existe en versi\u00f3n FastAPI<\/a>.<\/p>\n\n\n\n

C\u00f3mo funciona el bot<\/h2>\n\n\n\n
    \n
  1. El cliente env\u00eda un mensaje a tu n\u00famero.<\/li>\n\n\n
  2. Meta env\u00eda un POST<\/code> con el evento a la URL de tu webhook.<\/li>\n\n\n
  3. El servidor valida la firma, responde 200<\/code> de inmediato y procesa el evento despu\u00e9s.<\/li>\n\n\n
  4. El bot llama a POST \/<PHONE_NUMBER_ID>\/messages<\/code> para responder.<\/li>\n\n<\/ol>\n\n\n\n

    Como la respuesta sale justo despu\u00e9s del mensaje del cliente, est\u00e1 dentro de la ventana de atenci\u00f3n de 24 horas y puede ser texto libre o un mensaje interactivo, sin plantilla. Para una visi\u00f3n general de c\u00f3mo acceder a la API, mira la gu\u00eda de WhatsApp Cloud API<\/a>.<\/p>\n\n\n\n

    Qu\u00e9 necesitas antes<\/h2>\n\n\n\n
    Variable<\/th>Qu\u00e9 es<\/th>D\u00f3nde encontrarla<\/th><\/tr><\/thead>
    PHONE_NUMBER_ID<\/code><\/td>ID del n\u00famero en la Cloud API<\/td>Panel de apps, secci\u00f3n de WhatsApp<\/td><\/tr>
    ACCESS_TOKEN<\/code><\/td>Token con el permiso whatsapp_business_messaging<\/code><\/td>Token de usuario del sistema<\/td><\/tr>
    APP_SECRET<\/code><\/td>Clave secreta de la app, usada en la firma<\/td>Configuraci\u00f3n de la app > B\u00e1sica<\/td><\/tr>
    VERIFY_TOKEN<\/code><\/td>Cualquier texto que elijas<\/td>Lo defines t\u00fa y lo repites en el panel<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Usa un token permanente de usuario del sistema<\/a>, porque el token temporal del panel vence. El n\u00famero tambi\u00e9n debe estar registrado en la Cloud API, con el PIN de verificaci\u00f3n en dos pasos definido.<\/p>\n\n\n\n

    Necesitas Node.js 18 o superior, que es la versi\u00f3n m\u00ednima que exige Express 5 y ya incluye fetch<\/code> global, sin necesidad de axios.<\/p>\n\n\n\n

    1. Prepara el proyecto<\/h2>\n\n\n\n
    mkdir bot-whatsapp && cd bot-whatsapp\nnpm init -y\nnpm pkg set type=module\nnpm install express@5<\/code><\/pre>\n\n\n\n
    type=module<\/code> permite usar import<\/code>. Crea el archivo server.js<\/code>. Los bloques de c\u00f3digo de las secciones 1 a 5 forman el archivo completo: p\u00e9galos en orden.<\/p>\n\n\n\n
    import crypto from 'node:crypto';\nimport express from 'express';\n\nconst {\n  VERIFY_TOKEN,\n  ACCESS_TOKEN,\n  APP_SECRET = '',\n  WEBHOOK_KEY = '',\n  PHONE_NUMBER_ID = '',\n  PORT = 3000,\n} = process.env;\nconst API_URL =\n  process.env.API_URL ?? `https:\/\/graph.facebook.com\/v26.0\/${PHONE_NUMBER_ID}\/messages`;\n\nconst app = express();\nconst processed = new Set(); \/\/ en producci\u00f3n, usa Redis o tu base de datos<\/code><\/pre>\n\n\n\n
    API_URL<\/code> usa por defecto la Graph API de Meta. Para usar Vectalk, cambias esta variable y el token, como se muestra en la secci\u00f3n sobre Vectalk.<\/p>\n\n\n\n
    2. Verificaci\u00f3n del webhook (GET)<\/h2>\n\n\n\n
    Cuando guardas la URL de callback en el panel, Meta env\u00eda un GET<\/code> con hub.mode=subscribe<\/code>, hub.verify_token<\/code> y hub.challenge<\/code>. Si el token coincide, responde 200<\/code> con el valor de hub.challenge<\/code>. Cualquier otra respuesta deja el endpoint sin verificar y Meta no env\u00eda eventos.<\/p>\n\n\n\n
    app.get('\/webhook', (req, res) => {\n  const mode = req.query['hub.mode'];\n  const token = req.query['hub.verify_token'];\n  if (mode === 'subscribe' && token === VERIFY_TOKEN) {\n    return res.status(200).send(req.query['hub.challenge']);\n  }\n  res.sendStatus(403);\n});<\/code><\/pre>\n\n\n\n
    3. Validar la firma con express.raw<\/h2>\n\n\n\n
    Cada POST<\/code> de Meta trae X-Hub-Signature-256: sha256=<hash><\/code>, un HMAC-SHA256 del cuerpo calculado con la clave secreta de la app. El hash debe calcularse sobre los bytes exactos que llegaron. Si express.json()<\/code> ya convirti\u00f3 el cuerpo en objeto, JSON.stringify<\/code> no devuelve los mismos bytes y la firma nunca coincide.<\/p>\n\n\n\n
    La soluci\u00f3n es usar express.raw<\/code> solo en la ruta del webhook. Seg\u00fan la documentaci\u00f3n de Express, este middleware deja el cuerpo en req.body<\/code> como Buffer<\/code>, pero solo cuando el Content-Type<\/code> coincide con la opci\u00f3n type<\/code>, cuyo valor por defecto es application\/octet-stream<\/code>. Como Meta env\u00eda application\/json<\/code>, hay que indicar type: 'application\/json'<\/code>.<\/p>\n\n\n\n
    function signatureOk(rawBody, header = '') {\n  if (!APP_SECRET) return true;\n  const expected =\n    'sha256=' + crypto.createHmac('sha256', APP_SECRET).update(rawBody).digest('hex');\n  const a = Buffer.from(expected);\n  const b = Buffer.from(header);\n  return a.length === b.length && crypto.timingSafeEqual(a, b);\n}<\/code><\/pre>\n\n\n\n
    crypto.timingSafeEqual<\/code> compara en tiempo constante, pero lanza un error si los buffers tienen tama\u00f1os distintos. Por eso el c\u00f3digo revisa el tama\u00f1o antes.<\/p>\n\n\n\n
    Tres errores comunes en este paso:<\/p>\n\n\n\n