{"id":24488,"library":"pywa","title":"pywa - Python WhatsApp Bot Framework","description":"Pywa (Python WhatsApp API) is a powerful, fast, and easy-to-use framework for building WhatsApp bots in Python. It wraps the WhatsApp Business API (Cloud API) and provides a clean, event-driven interface for handling messages, callbacks, and sending rich media. Version 3.9.0 requires Python >=3.10. The library follows a monthly release cadence.","status":"active","version":"3.9.0","language":"python","source_language":"en","source_url":"https://github.com/daoodaba975/pywa","tags":["whatsapp","bot","cloud-api","webhook","messaging"],"install":[{"cmd":"pip install pywa","lang":"bash","label":"Install pywa"}],"dependencies":[{"reason":"Used for HTTP calls to WhatsApp API","package":"requests","optional":false},{"reason":"Used for webhook signature verification","package":"cryptography","optional":true}],"imports":[{"note":"Main client class","wrong":null,"symbol":"WhatsApp","correct":"from pywa import WhatsApp"},{"note":"Message type for incoming messages","wrong":null,"symbol":"Message","correct":"from pywa.types import Message"},{"note":"Type for callback button interactions","wrong":null,"symbol":"CallbackButton","correct":"from pywa.types import CallbackButton"},{"note":"No common mistake reported","wrong":"from pywa.types import CallbackData (still correct but in older versions it was in pywa.types.callback)","symbol":"CallbackData","correct":"from pywa.types import CallbackData"}],"quickstart":{"code":"import os\nfrom pywa import WhatsApp\n\nwa = WhatsApp(\n    phone_id=os.environ['PHONE_ID'],\n    token=os.environ['TOKEN'],\n    server='http://localhost:8080',\n    verify_token='my_verify_token'\n)\n\n@wa.on_message()\ndef handle_message(client: WhatsApp, message):\n    client.send_message(to=message.from_user, text=f'You said: {message.text}')\n\nwa.run()","lang":"python","description":"Initialize the WhatsApp client, define a message handler, and start the webhook server."},"warnings":[{"fix":"Use keyword arguments: WhatsApp(phone_id=..., token=..., server=..., verify_token=...)","message":"In pywa 3.x, the constructor changed: `verify_token` is now positional (first argument) and `server` parameter changed to accept a string URL instead of a tuple. Old code passing arguments positionally may break.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `@wa.on_callback_button()` with `@wa.on_callback_query()`","message":"The `on_callback_button` handler is deprecated since 3.4.0; use `on_callback_query` instead.","severity":"deprecated","affected_versions":">=3.4.0"},{"fix":"Pass a `verify_token` in the constructor and verify on your server platform (e.g., using the 'cryptography' library if you enable signature checking).","message":"Webhook signature verification is not mandatory by default. If you don't set a `verify_token`, you risk processing unverified requests. Always set a secure `verify_token` in production.","severity":"gotcha","affected_versions":"all"},{"fix":"Use the `id` attribute of the returned `MessageStatus` object instead of parsing the response.","message":"In pywa 3.0, the `send_message` method no longer returns the raw API response as `requests.Response` but returns a `MessageStatus` object. Accessing `.json()` on the return value will fail.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Update pywa to >=3.0.0 and use `from pywa import WhatsApp` and decorate with `@wa.on_message()`.","cause":"Using an outdated version where the decorator syntax was different or not yet supported. Also, forgetting to import the decorator from pywa.","error":"AttributeError: 'WhatsApp' object has no attribute 'on_message'"},{"fix":"Use keyword arguments: `WhatsApp(phone_id='...', token='...', server='...', verify_token='...')`","cause":"Passing arguments positionally in wrong order; `verify_token` is now the first positional argument (if using positional style) or better use keyword arguments.","error":"TypeError: __init__() got multiple values for argument 'phone_id'"},{"fix":"Set `server='http://localhost:8080'` (include http:// and no trailing slash) or use a valid URL.","cause":"The server argument expects the full URL to the webhook endpoint. If you omit the trailing slash or don't start with http://, it may fail.","error":"requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: / (Caused by NewConnectionError)"},{"fix":"Provide a non-empty string as `verify_token` parameter.","cause":"Passing an empty string or None as verify_token; it must be provided and non-empty.","error":"ValueError: The 'verify_token' must be a non-empty string"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}