{"id":540,"date":"2026-10-28T16:07:09","date_gmt":"2026-10-28T16:07:09","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/bot-whatsapp-nodejs-api-oficial\/"},"modified":"2026-10-28T16:07:11","modified_gmt":"2026-10-28T16:07:11","slug":"bot-whatsapp-nodejs-api-oficial","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/bot-whatsapp-nodejs-api-oficial\/","title":{"rendered":"Bot de WhatsApp com Node.js na API oficial (Express, do zero)"},"content":{"rendered":"\n

Atualizado em 28\/10\/2026<\/em><\/p>\n\n\n\n

Para criar um bot de WhatsApp com Node.js na API oficial, voc\u00ea precisa de um servidor Express com HTTPS e duas rotas: um GET<\/code> que devolve o desafio de verifica\u00e7\u00e3o da Meta e um POST<\/code> que recebe as mensagens, valida a assinatura X-Hub-Signature-256<\/code> sobre o corpo bruto (com express.raw<\/code>) e responde pelo endpoint \/messages<\/code> da Cloud API usando o fetch<\/code> nativo. Sem SDK e sem depend\u00eancias al\u00e9m do Express, tudo cabe em um arquivo de cerca de 150 linhas.<\/p>\n\n\n\n

O bot final responde “oi” ou “menu” com tr\u00eas bot\u00f5es, trata o toque em cada bot\u00e3o, marca a mensagem como lida, ignora eventos repetidos e roda em produ\u00e7\u00e3o com Docker e HTTPS autom\u00e1tico. O c\u00f3digo foi testado com Express 5.3 e Node.js 26, e funciona direto na Meta ou pela Vectalk, mudando s\u00f3 duas vari\u00e1veis de ambiente. Se voc\u00ea prefere Python, o mesmo bot existe em vers\u00e3o FastAPI<\/a>.<\/p>\n\n\n\n

Como o bot funciona<\/h2>\n\n\n\n
    \n
  1. O cliente manda uma mensagem para o seu n\u00famero.<\/li>\n\n\n
  2. A Meta envia um POST<\/code> com o evento para a URL do seu webhook.<\/li>\n\n\n
  3. O servidor valida a assinatura, responde 200<\/code> na hora e processa o evento depois.<\/li>\n\n\n
  4. O bot chama POST \/<PHONE_NUMBER_ID>\/messages<\/code> para responder.<\/li>\n\n<\/ol>\n\n\n\n

    Como a resposta sai logo depois da mensagem do cliente, ela est\u00e1 dentro da janela de 24 horas<\/a> e pode ser texto livre ou mensagem interativa, sem template. Para a vis\u00e3o geral de como acessar a API, veja o guia da API oficial do WhatsApp<\/a>.<\/p>\n\n\n\n

    O que voc\u00ea precisa antes<\/h2>\n\n\n\n
    Vari\u00e1vel<\/th>O que \u00e9<\/th>Onde encontrar<\/th><\/tr><\/thead>
    PHONE_NUMBER_ID<\/code><\/td>ID do n\u00famero na Cloud API<\/td>Painel de Apps, na se\u00e7\u00e3o do WhatsApp<\/td><\/tr>
    ACCESS_TOKEN<\/code><\/td>Token com permiss\u00e3o whatsapp_business_messaging<\/code><\/td>Token de usu\u00e1rio do sistema<\/td><\/tr>
    APP_SECRET<\/code><\/td>Chave secreta do app, usada na assinatura<\/td>Configura\u00e7\u00f5es do app > B\u00e1sico<\/td><\/tr>
    VERIFY_TOKEN<\/code><\/td>Texto qualquer escolhido por voc\u00ea<\/td>Voc\u00ea define e repete no painel<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Use um token permanente de usu\u00e1rio do sistema<\/a>, porque o token tempor\u00e1rio do painel expira. O n\u00famero tamb\u00e9m precisa estar registrado na Cloud API, com o PIN de duas etapas definido.<\/p>\n\n\n\n

    No ambiente, voc\u00ea precisa de Node.js 18 ou mais recente, que \u00e9 a vers\u00e3o m\u00ednima exigida pelo Express 5 e j\u00e1 traz o fetch<\/code> global, sem precisar de axios.<\/p>\n\n\n\n

    1. Prepare o projeto<\/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
    O type=module<\/code> permite usar import<\/code>. Crie o arquivo server.js<\/code>. Os blocos de c\u00f3digo das se\u00e7\u00f5es 1 a 5 formam o arquivo completo: cole cada um em sequ\u00eancia.<\/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(); \/\/ em produ\u00e7\u00e3o, use Redis ou o banco<\/code><\/pre>\n\n\n\n
    API_URL<\/code> usa a Graph API da Meta como padr\u00e3o. Para usar a Vectalk, voc\u00ea troca essa vari\u00e1vel e o token, como mostra a se\u00e7\u00e3o sobre a Vectalk.<\/p>\n\n\n\n
    2. Verifica\u00e7\u00e3o do webhook (GET)<\/h2>\n\n\n\n
    Quando voc\u00ea salva a URL de callback no painel, a Meta manda um GET<\/code> com hub.mode=subscribe<\/code>, hub.verify_token<\/code> e hub.challenge<\/code>. Se o token bater, responda 200<\/code> com o valor de hub.challenge<\/code>. Qualquer outra resposta deixa o endpoint n\u00e3o verificado, e a Meta n\u00e3o envia 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 a assinatura com express.raw<\/h2>\n\n\n\n
    Todo POST<\/code> da Meta traz X-Hub-Signature-256: sha256=<hash><\/code>, um HMAC-SHA256 do corpo calculado com a chave secreta do app. O hash precisa ser calculado sobre os bytes exatos que chegaram. Se o express.json()<\/code> j\u00e1 transformou o corpo em objeto, JSON.stringify<\/code> n\u00e3o devolve os mesmos bytes, e a assinatura nunca bate.<\/p>\n\n\n\n
    A solu\u00e7\u00e3o \u00e9 usar express.raw<\/code> s\u00f3 na rota do webhook. Segundo a documenta\u00e7\u00e3o do Express, esse middleware coloca o corpo em req.body<\/code> como Buffer<\/code>, mas apenas quando o Content-Type<\/code> combina com a op\u00e7\u00e3o type<\/code>, cujo padr\u00e3o \u00e9 application\/octet-stream<\/code>. Como a Meta envia application\/json<\/code>, \u00e9 preciso informar 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 em tempo constante, mas lan\u00e7a erro se os buffers tiverem tamanhos diferentes. Por isso o c\u00f3digo checa o tamanho antes.<\/p>\n\n\n\n
    Tr\u00eas erros comuns nessa etapa:<\/p>\n\n\n\n