Install & Compatibility
Where this runs
tested against v4.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WhatsApp
✓ from pywa import WhatsApp
Main client class
Message
✓ from pywa.types import Message
Message type for incoming messages
CallbackButton
✓ from pywa.types import CallbackButton
Type for callback button interactions
CallbackData
✓ from pywa.types import CallbackData
✗ from pywa.types import CallbackData (still correct but in older versions it was in pywa.types.callback)
No common mistake reported
Initialize the WhatsApp client, define a message handler, and start the webhook server.
import os
from pywa import WhatsApp
wa = WhatsApp(
phone_id=os.environ['PHONE_ID'],
token=os.environ['TOKEN'],
server='http://localhost:8080',
verify_token='my_verify_token'
)
@wa.on_message()
def handle_message(client: WhatsApp, message):
client.send_message(to=message.from_user, text=f'You said: {message.text}')
wa.run()
Errors
Common errors & fixes
AttributeError: 'WhatsApp' object has no attribute 'on_message'
Using an outdated version where the decorator syntax was different or not yet supported. Also, forgetting to import the decorator from pywa.
fixUpdate pywa to >=3.0.0 and use `from pywa import WhatsApp` and decorate with `@wa.on_message()`.
TypeError: __init__() got multiple values for argument 'phone_id'
Passing arguments positionally in wrong order; `verify_token` is now the first positional argument (if using positional style) or better use keyword arguments.
fixUse keyword arguments: `WhatsApp(phone_id='...', token='...', server='...', verify_token='...')`
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: / (Caused by NewConnectionError)
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.
fixSet `server='http://localhost:8080'` (include http:// and no trailing slash) or use a valid URL.
ValueError: The 'verify_token' must be a non-empty string
Passing an empty string or None as verify_token; it must be provided and non-empty.
fixProvide a non-empty string as `verify_token` parameter.
Upgrade
Version history
4.2.0latest on PyPI · released Jun 19, 2026
Audit
Dependencies
requestsrequiredUsed for HTTP calls to WhatsApp API
cryptographyoptionalUsed for webhook signature verification