{"id":541,"date":"2026-10-28T16:07:09","date_gmt":"2026-10-28T16:07:09","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/whatsapp-bot-nodejs-express\/"},"modified":"2026-10-28T16:07:13","modified_gmt":"2026-10-28T16:07:13","slug":"whatsapp-bot-nodejs-express","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/whatsapp-bot-nodejs-express\/","title":{"rendered":"How to Build a WhatsApp Bot in Node.js with Express (Official Cloud API, from Scratch)"},"content":{"rendered":"\n

Updated on October 28, 2026<\/em><\/p>\n\n\n\n

To build a WhatsApp bot in Node.js on the official API, you need an Express server behind HTTPS with two routes: a GET<\/code> that returns Meta’s verification challenge and a POST<\/code> that receives messages, validates the X-Hub-Signature-256<\/code> signature over the raw body (using express.raw<\/code>) and replies through the Cloud API \/messages<\/code> endpoint with native fetch<\/code>. No SDK and no dependencies besides Express: it all fits in a single file of about 150 lines.<\/p>\n\n\n\n

The finished bot answers “hi” or “menu” with three buttons, handles each button tap, marks messages as read, ignores duplicate events and runs in production with Docker and automatic HTTPS. The code was tested with Express 5.3 on Node.js 26 and works directly with Meta or through Vectalk by changing two environment variables. If you prefer Python, the same bot exists as a FastAPI version<\/a>.<\/p>\n\n\n\n

How the bot works<\/h2>\n\n\n\n
    \n
  1. A customer sends a message to your WhatsApp Business number.<\/li>\n\n\n
  2. Meta sends a POST<\/code> with the event to your webhook URL.<\/li>\n\n\n
  3. The server validates the signature, returns 200<\/code> right away and processes the event afterwards.<\/li>\n\n\n
  4. The bot calls POST \/<PHONE_NUMBER_ID>\/messages<\/code> to reply.<\/li>\n\n<\/ol>\n\n\n\n

    Because the reply goes out right after the customer’s message, it falls inside the 24-hour customer service window, so it can be free-form text or an interactive message with no template. For an overview of how to get API access, see the WhatsApp Cloud API guide<\/a>.<\/p>\n\n\n\n

    What you need first<\/h2>\n\n\n\n
    Variable<\/th>What it is<\/th>Where to find it<\/th><\/tr><\/thead>
    PHONE_NUMBER_ID<\/code><\/td>The number’s ID on the Cloud API<\/td>App Dashboard, WhatsApp section<\/td><\/tr>
    ACCESS_TOKEN<\/code><\/td>Token with the whatsapp_business_messaging<\/code> permission<\/td>System user token<\/td><\/tr>
    APP_SECRET<\/code><\/td>App secret, used for the signature<\/td>App settings > Basic<\/td><\/tr>
    VERIFY_TOKEN<\/code><\/td>Any string you choose<\/td>You set it and repeat it in the dashboard<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Use a permanent system user access token<\/a>, because the temporary dashboard token expires. The number also has to be registered on the Cloud API, with its two-step verification PIN set.<\/p>\n\n\n\n

    You need Node.js 18 or newer, which is the minimum Express 5 requires and already ships a global fetch<\/code>, so there is no need for axios.<\/p>\n\n\n\n

    1. Set up the project<\/h2>\n\n\n\n
    mkdir whatsapp-bot && cd whatsapp-bot\nnpm init -y\nnpm pkg set type=module\nnpm install express@5<\/code><\/pre>\n\n\n\n
    type=module<\/code> lets you use import<\/code>. Create server.js<\/code>. The code blocks in sections 1 to 5 make up the complete file: paste them in order.<\/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(); \/\/ in production, use Redis or your database<\/code><\/pre>\n\n\n\n
    API_URL<\/code> defaults to Meta’s Graph API. To use Vectalk, you swap this variable and the token, as shown in the Vectalk section.<\/p>\n\n\n\n
    2. Webhook verification (GET)<\/h2>\n\n\n\n
    When you save the callback URL in the dashboard, Meta sends a GET<\/code> with hub.mode=subscribe<\/code>, hub.verify_token<\/code> and hub.challenge<\/code>. If the token matches, return 200<\/code> with the hub.challenge<\/code> value. Any other response leaves the endpoint unverified, and Meta won’t send events.<\/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. Validate the signature with express.raw<\/h2>\n\n\n\n
    Every POST<\/code> from Meta carries X-Hub-Signature-256: sha256=<hash><\/code>, an HMAC-SHA256 of the body keyed with your app secret. The hash must be computed over the exact bytes that arrived. If express.json()<\/code> has already turned the body into an object, JSON.stringify<\/code> won’t give you the same bytes back, and the signature will never match.<\/p>\n\n\n\n
    The fix is to use express.raw<\/code> on the webhook route only. According to the Express docs, this middleware puts the body in req.body<\/code> as a Buffer<\/code>, but only when the Content-Type<\/code> matches the type<\/code> option, which defaults to application\/octet-stream<\/code>. Meta sends application\/json<\/code>, so you must pass 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> compares in constant time but throws if the buffers have different lengths, which is why the code checks the length first.<\/p>\n\n\n\n
    Three common mistakes at this step:<\/p>\n\n\n\n