{"id":536,"date":"2026-10-28T16:06:52","date_gmt":"2026-10-28T16:06:52","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/bot-whatsapp-python-fastapi\/"},"modified":"2026-10-28T16:07:03","modified_gmt":"2026-10-28T16:07:03","slug":"bot-whatsapp-python-fastapi","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/bot-whatsapp-python-fastapi\/","title":{"rendered":"Bot de WhatsApp con Python en la API oficial (FastAPI, desde cero)"},"content":{"rendered":"\n

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

Para crear un bot de WhatsApp con Python en la API oficial necesitas un servidor HTTPS con dos rutas: un GET<\/code> que responde al desaf\u00edo de verificaci\u00f3n de Meta y un POST<\/code> que recibe los mensajes, valida la firma X-Hub-Signature-256<\/code> y contesta llamando al endpoint \/messages<\/code> de la Cloud API. Con FastAPI y httpx todo cabe en un archivo de unas 150 l\u00edneas, y eso es lo que este tutorial arma desde cero.<\/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 FastAPI 0.128 y funciona tanto directo con Meta como a trav\u00e9s de Vectalk, cambiando solo dos variables de entorno.<\/p>\n\n\n\n

C\u00f3mo funciona el bot<\/h2>\n\n\n\n

El flujo tiene cuatro pasos:<\/p>\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. Tu servidor valida la firma, responde 200<\/code> de inmediato y procesa el evento en segundo plano.<\/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. Si todav\u00eda est\u00e1s decidiendo c\u00f3mo acceder a la API, la gu\u00eda de WhatsApp Cloud API<\/a> explica las opciones.<\/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>: el token temporal del panel vence y tumba el bot. El n\u00famero tambi\u00e9n debe estar registrado en la Cloud API; si todav\u00eda no lo est\u00e1, mira c\u00f3mo registrar el n\u00famero<\/a>.<\/p>\n\n\n\n

    En tu m\u00e1quina necesitas Python 3.10 o superior.<\/p>\n\n\n\n

    1. Prepara el proyecto<\/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
    El paquete fastapi[standard]<\/code> instala Uvicorn y el comando fastapi<\/code>. httpx hace las llamadas as\u00edncronas a la API.<\/p>\n\n\n\n
    Crea el archivo main.py<\/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 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()  # en producci\u00f3n, usa Redis o tu base de datos<\/code><\/pre>\n\n\n\n
    API_URL<\/code> usa por defecto la URL de Meta. Para usar Vectalk, solo cambias esta variable y el token, como se muestra m\u00e1s abajo.<\/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 con el tuyo, responde 200<\/code> con el valor de hub.challenge<\/code> en texto plano. Cualquier otra respuesta deja el endpoint sin verificar y Meta no env\u00eda 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
    Los nombres de los par\u00e1metros llevan punto (hub.mode<\/code>), por eso el c\u00f3digo lee request.query_params<\/code> en lugar de declarar par\u00e1metros en la funci\u00f3n.<\/p>\n\n\n\n
    3. Validar la firma X-Hub-Signature-256<\/h2>\n\n\n\n
    Cada POST<\/code> de Meta trae el encabezado X-Hub-Signature-256: sha256=<hash><\/code>. El hash es un HMAC-SHA256 del cuerpo de la solicitud, calculado con la clave secreta de la app. Sin esta validaci\u00f3n, cualquiera que descubra tu URL puede falsificar mensajes 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
    Dos cuidados que ahorran horas de depuraci\u00f3n:<\/p>\n\n\n\n