{"id":535,"date":"2026-10-28T16:06:51","date_gmt":"2026-10-28T16:06:51","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/whatsapp-bot-python-fastapi\/"},"modified":"2026-10-28T16:06:55","modified_gmt":"2026-10-28T16:06:55","slug":"whatsapp-bot-python-fastapi","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/whatsapp-bot-python-fastapi\/","title":{"rendered":"How to Build a WhatsApp Bot in Python with FastAPI (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 Python on the official API, you need an HTTPS server with two routes: a GET<\/code> that answers Meta’s verification challenge and a POST<\/code> that receives messages, validates the X-Hub-Signature-256<\/code> signature and replies by calling the Cloud API \/messages<\/code> endpoint. With FastAPI and httpx, that fits in a single file of about 150 lines, and this tutorial builds it from scratch.<\/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 FastAPI 0.128 and works both directly with Meta and through Vectalk by changing two environment variables.<\/p>\n\n\n\n

How the bot works<\/h2>\n\n\n\n

The flow has four steps:<\/p>\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. Your server validates the signature, returns 200<\/code> right away and processes the event in the background.<\/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. If you are still deciding how to access the API, the WhatsApp Cloud API guide<\/a> covers the options.<\/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>: the temporary token from the dashboard expires and takes the bot down with it. The number must also be registered on the Cloud API; if it isn’t yet, see how to register the number<\/a>.<\/p>\n\n\n\n

    Locally, you need Python 3.10 or newer.<\/p>\n\n\n\n

    1. Set up the project<\/h2>\n\n\n\n
    mkdir whatsapp-bot && cd whatsapp-bot\npython -m venv .venv\nsource .venv\/bin\/activate\npip install \"fastapi[standard]\" httpx<\/code><\/pre>\n\n\n\n
    fastapi[standard]<\/code> installs Uvicorn and the fastapi<\/code> command. httpx makes the async calls to the API.<\/p>\n\n\n\n
    Create main.py<\/code>. The code blocks in sections 1 to 5 make up the complete file: paste them in order.<\/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()  # 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 only change this variable and the token, as shown in the Vectalk section below.<\/p>\n\n\n\n
    2. Webhook verification (GET)<\/h2>\n\n\n\n
    When you save the callback URL in the App Dashboard, Meta sends a GET<\/code> with hub.mode=subscribe<\/code>, hub.verify_token<\/code> and hub.challenge<\/code>. If the token matches yours, return 200<\/code> with the hub.challenge<\/code> value as plain text. Any other response leaves the endpoint unverified, and Meta won’t send events.<\/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
    The parameter names contain a dot (hub.mode<\/code>), which is why the code reads request.query_params<\/code> instead of declaring function parameters.<\/p>\n\n\n\n
    3. Validate the X-Hub-Signature-256 header<\/h2>\n\n\n\n
    Every POST<\/code> from Meta carries the header X-Hub-Signature-256: sha256=<hash><\/code>. The hash is an HMAC-SHA256 of the request body, keyed with your app secret. Without this check, anyone who finds your URL can forge customer messages.<\/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
    Two details that save hours of debugging:<\/p>\n\n\n\n