{"id":534,"date":"2026-10-28T16:06:51","date_gmt":"2026-10-28T16:06:51","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/bot-whatsapp-python-api-oficial\/"},"modified":"2026-10-28T16:06:53","modified_gmt":"2026-10-28T16:06:53","slug":"bot-whatsapp-python-api-oficial","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/bot-whatsapp-python-api-oficial\/","title":{"rendered":"Bot de WhatsApp com Python na API oficial (FastAPI, do zero)"},"content":{"rendered":"\n

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

Para criar um bot de WhatsApp com Python na API oficial, voc\u00ea precisa de um servidor HTTPS com duas rotas: um GET<\/code> que responde ao desafio de verifica\u00e7\u00e3o da Meta e um POST<\/code> que recebe as mensagens, valida a assinatura X-Hub-Signature-256<\/code> e responde chamando o endpoint \/messages<\/code> da Cloud API. Com FastAPI e httpx isso cabe em um arquivo de cerca de 150 linhas, e \u00e9 o que este tutorial monta do zero.<\/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 FastAPI 0.128 e funciona tanto direto na Meta quanto pela Vectalk, mudando s\u00f3 duas vari\u00e1veis de ambiente.<\/p>\n\n\n\n

Como o bot funciona<\/h2>\n\n\n\n

O fluxo tem quatro passos:<\/p>\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 seu servidor valida a assinatura, responde 200<\/code> na hora e processa o evento em segundo plano.<\/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. Se voc\u00ea ainda est\u00e1 decidindo como acessar a API, o guia da API oficial do WhatsApp<\/a> explica as op\u00e7\u00f5es.<\/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>: o token tempor\u00e1rio do painel expira e derruba o bot. O n\u00famero tamb\u00e9m precisa estar registrado na Cloud API; se ainda n\u00e3o est\u00e1, veja como registrar o n\u00famero<\/a>.<\/p>\n\n\n\n

    No ambiente local, voc\u00ea precisa de Python 3.10 ou mais recente.<\/p>\n\n\n\n

    1. Prepare o projeto<\/h2>\n\n\n\n
    mkdir bot-whatsapp && cd bot-whatsapp\npython -m venv .venv\nsource .venv\/bin\/activate\npip install \"fastapi[standard]\" httpx<\/code><\/pre>\n\n\n\n
    O pacote fastapi[standard]<\/code> traz o Uvicorn e o comando fastapi<\/code>. O httpx faz as chamadas ass\u00edncronas para a API.<\/p>\n\n\n\n
    Crie o arquivo main.py<\/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 hashlib\nimport hmac\nimport json\nimport logging\nimport os\n\nimport httpx\nfrom fastapi import BackgroundTasks, FastAPI, HTTPException, Request\nfrom fastapi.responses import PlainTextResponse\n\nVERIFY_TOKEN = os.environ[\"VERIFY_TOKEN\"]\nACCESS_TOKEN = os.environ[\"ACCESS_TOKEN\"]\nAPP_SECRET = os.environ.get(\"APP_SECRET\", \"\")\nWEBHOOK_KEY = os.environ.get(\"WEBHOOK_KEY\", \"\")\nPHONE_NUMBER_ID = os.environ.get(\"PHONE_NUMBER_ID\", \"\")\nAPI_URL = os.environ.get(\n    \"API_URL\", f\"https:\/\/graph.facebook.com\/v26.0\/{PHONE_NUMBER_ID}\/messages\"\n)\n\nlog = logging.getLogger(\"bot\")\napp = FastAPI()\nclient = httpx.AsyncClient(timeout=10)\nprocessed = set()  # em produ\u00e7\u00e3o, use Redis ou o banco<\/code><\/pre>\n\n\n\n
    API_URL<\/code> tem a URL da Meta como padr\u00e3o. Para usar a Vectalk, voc\u00ea s\u00f3 troca essa vari\u00e1vel e o token, como mostra a se\u00e7\u00e3o sobre a Vectalk mais abaixo.<\/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 com o seu, responda 200<\/code> com o valor de hub.challenge<\/code> em texto puro. Qualquer outra resposta deixa o endpoint como n\u00e3o verificado, e a Meta n\u00e3o envia eventos.<\/p>\n\n\n\n
    @app.get(\"\/webhook\")\ndef verify(request: Request):\n    q = request.query_params\n    if q.get(\"hub.mode\") == \"subscribe\" and q.get(\"hub.verify_token\") == VERIFY_TOKEN:\n        return PlainTextResponse(q.get(\"hub.challenge\", \"\"))\n    raise HTTPException(status_code=403)<\/code><\/pre>\n\n\n\n
    Os nomes dos par\u00e2metros t\u00eam ponto (hub.mode<\/code>), por isso o c\u00f3digo l\u00ea request.query_params<\/code> em vez de declarar par\u00e2metros na fun\u00e7\u00e3o.<\/p>\n\n\n\n
    3. Validar a assinatura X-Hub-Signature-256<\/h2>\n\n\n\n
    Todo POST<\/code> da Meta traz o cabe\u00e7alho X-Hub-Signature-256: sha256=<hash><\/code>. O hash \u00e9 um HMAC-SHA256 do corpo da requisi\u00e7\u00e3o, calculado com a chave secreta do app. Sem essa checagem, qualquer pessoa que descubra sua URL consegue fingir mensagens de clientes.<\/p>\n\n\n\n
    def signature_ok(body: bytes, header: str) -> bool:\n    if not APP_SECRET:\n        return True\n    expected = \"sha256=\" + hmac.new(APP_SECRET.encode(), body, hashlib.sha256).hexdigest()\n    return hmac.compare_digest(expected, header or \"\")<\/code><\/pre>\n\n\n\n
    Dois cuidados que evitam horas de depura\u00e7\u00e3o:<\/p>\n\n\n\n