4.4.0

What's Changed

Update with pip: pip3 install -U "pywa[server]"

• [server] enhance logging infrastructure with update hash and context binding (try pywa dev --log-level debug)
• [cli] add commands to list and download official example bots from GitHub (try pywa new examples)
• [flows] expose Condition and MathExpression tp allow repr(FlowJSON) to be copy-paste
• [flows] adding flow_token_signature to FlowRequest
• [types] [types] rename messaging_limit_tier to whatsapp_business_manager_messaging_limit and add deprecation warning. reported by @aleinv18 in #221
• [helpers] allowing to disable GeneratorStreamer usage with the USE_FAKE_GEN_STREAM flag when uploading media from url
• [helpers] cache the flow private key instead of parsing it per request. added by @ashbrener in #219
• [project] adding ty for type checking and linting
• [project] update dependency management to use uv for installation and syncing

Full Changelog: 4.3.1...4.4.0

4.3.1

What's Changed

Update with pip: pip3 install -U "pywa[server]"

• [callback] treat missing message context as no reply_to_message by @WouterDurnez in #216
• [types] deprecate caller and callee properties as part of BSUID changes
• [sent_update] better recipient type resolving
• [enums] adding copy-paste-compatible repr for UploadedBy and UserIdentifier

Full Changelog: 4.3.0...4.3.1

4.3.0

What's Changed

Update with pip: pip3 install -U "pywa[server]"

• [filters] make Filter class generic
• [signups] adding support for creating listing and updating signups
• [templates] add documentation and strict typing for ContactInfoRequestButton
• [message] deprecate sender and recipient properties and update user identifier priority
• [cli] move uvicorn import to runtime and improve error handling
• [errors] add more error codes for throttling, sending, and migration, and fix template error code

from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

@wa.on_callback_button(filters.text) # Type checker will catch this error
def on_callback(_: WhatsApp, button: types.CallbackButton):
    ...

Full Changelog: 4.2.0...4.3.0

4.2.1

What's Changed

Update with pip: pip3 install -U "pywa[server]"

• [others] fix parsing contact with field request contact
• [others] fix parsing contact without name
• [client] fix parsing get_reserved_usernames()
• [api] using json instead of data for encryption and template requests

Full Changelog: 4.2.0...4.2.1

4.2.0

What's Changed

Update with pip: pip3 install -U "pywa[server]"

• [filters] allowing filters.new to be used as decorator:
• [contacts] adding first_wa_id property to ContactList
• [api] fix recipient_type in send_marketing_message

from pywa import WhatsApp, filters, types

@filters.new  # create new filter by using the `filters.new` decorator on a function
def no_wa_id_in_db(_: WhatsApp, msg: types.Message) -> bool:
    return my_db.is_user_has_wa_id(bsuid=msg.from_user.bsuid)

@wa.on_message(filters.without_wa_id & no_wa_id_in_db, priority=100)
def handle_user_without_wa_id(_: WhatsApp, msg: types.Message):
    r = msg.reply_contact_info_request(text="Please share your contact to use this bot").wait_for_contact_info()
    r.reply("Thanks for sharing your contact, now you can use this bot")
    my_db.update_wa_id(bsuid=msg.from_user.bsuid, wa_id=r.contacts.first_wa_id) # use the `.first_wa_id` shortcut
    msg.continue_handling()

Full Changelog: 4.1.0...4.2.0

4.1.0

What's Changed

Update with pip: pip3 install -U "pywa[server]"

• [client] add archive_templates and unarchive_templates methods for template archival management
• [client] add force_transfer option to set_username method for username management
• [client] add request_contact_info method to request customer contact information
• [listners] add wait_for_contact_info method to wait for contact info requests
• [filters] add webhook_fields filter for filtering raw updates by fields
• [cli] improve error handling during CLI command execution
• [handlers] improve handler typing and inline documentation examples (suggested by @maxrabin in #207 and #208)
• [server] fix potential reflected XSS in the WebSub intent verification (reported by @randomstuff in #198)
• [api] add internal utility methods for filtering None values and joining fields

from pywa import WhatsApp, types, filters

wa = WhatsApp(...)

@wa.on_message(filters.without_wa_id, priority=100)
def handle_user_without_wa_id(_: WhatsApp, m: types.Message):
    r = m.reply_contact_info_request(text="Please share your contact to use this bot").wait_for_contact_info()
    r.reply(f"Thanks {r.contacts.first.name}! Your WhatsApp ID is: {r.contacts.first.phones[0].wa_id}")
    # save wa_id to your db

@wa.on_raw_update(filters.webhook_fields("video_calls")) # There are no video calls (yet). just an example
def on_video_call(_: WhatsApp, update: types.RawUpdate):
    print(f"New video call! {update.value}")

Full Changelog: 4.0.0...4.1.0

4.0.0

Pywa v4.0.0 is here!

Update with pip: pip3 install -U pywa

This is a massive update to Pywa, introducing BSUID, full group management, a built-in webhook server, Coexistence support, and more.

Important

Migration to v4 introduces breaking changes. Please review carefully before upgrading.

✨ Highlights

• User Identity & BSUID: Full support for Business-Scoped User IDs (BSUIDs), parent BSUIDs, usernames, and country_code. User.wa_id is now optional.
• Groups: Full group management support (create, update, delete, manage invite links/join requests). Added msg.chat to distinguish private chats from groups.
• Webhooks & CLI: New built-in server workflow (pywa dev, pywa run, WhatsApp.run()) and start_ngrok_tunnel for easy local development and testing.
• Messages & Media: Added EditedMessage, DeletedMessage, and Outgoing equivalents for Coexistence support. Added send_carousel and reply_carousel. Media objects now store their caption.
• Business Management: Retrieve shared/owned WABAs, create/verify phone numbers on WABAs, and manage usernames (set_username, delete_username, etc.).
• Templates: Better validation, easier component lookup, stricter URL variable checks, and Template.duplicate(...) now supports target_waba_id.

🔥 Breaking changes

• User Identity: User.wa_id may be None if a user enables a username. Store User.bsuid instead.
• ChatOpened: Removed completely (types.ChatOpened, handlers, and filters) → Use message, callback, or listener entry points.
• Listeners: Direct wa.listen(to="...") calls removed → Use explicit listener identifiers instead.
• System Messages: Message.system removed → System events are now handled via PhoneNumberChange and IdentityChange.
• Media: Message.download_media(in_memory=True) removed → Use msg.get_media_bytes() or msg.stream_media().
• Sent Updates: Destination is now exposed as sent.chat (with .id and .type) instead of a plain string in sent.to_user.

See full details and migration steps in the migration guide.

📚 Resources

• 📖 Documentation
• 💬 Community Telegram Chat

💡 Examples

• User Identity Storage (BSUID Readiness)

Old code often used wa_id as the only stable user key. In 4.x, store bsuid and treat wa_id as optional.

from pywa import WhatsApp, types

wa = WhatsApp(...)

def save_user_to_db(user: types.User):
    db.save_user(
        bsuid=user.bsuid,
        wa_id=user.wa_id,
        username=user.username,
        parent_bsuid=user.parent_bsuid,
        country_code=user.country_code,
        name=user.name,
    )

@wa.on_message
def on_message(_: WhatsApp, msg: types.Message):
    save_user_to_db(msg.from_user)
    msg.reply(f"Hello {msg.from_user.name}!")

• Run Webhooks with the New Built-in Server & Ngrok

You no longer need to strictly set up FastAPI or Flask just to host webhooks locally.

from pywa import WhatsApp, filters, types, utils

# Automatically setup an Ngrok tunnel for local testing
callback_url = utils.start_ngrok_tunnel(
    auth_token="NGROK_AUTH_TOKEN",
    domain="your-domain.ngrok-free.app",
)

wa = WhatsApp(
    phone_id="1234567890",
    token="EAA...",
    app_id="1234567890",
    app_secret="********",
    callback_url=callback_url,
    verify_token="my-verify-token",
)

@wa.on_message(filters.text)
def echo(_: WhatsApp, msg: types.Message):
    msg.reply(msg.text)

Run the application via the new CLI commands:

pywa dev
# or for production-style serving:
pywa run

Full Changelog: 3.9.0...4.0.0

4.0.0b7

What's Changed

Update with pip: pip install -U pywa --pre
Updated Docs: pywa.readthedocs.io/en/dev/

Caution

Make sure to read the migration guide before updating to this version!

• [helpers] fix incoming updates in fastapi and starlette
• [helpers] hide webhook endpoints from OpenAPI schema
• [ci] streamline publish workflow for PyPI

Full Changelog: 4.0.0b6...4.0.0b7

4.0.0b6

What's Changed

Update with pip: pip install -U pywa --pre
Updated Docs: pywa.readthedocs.io/en/dev/

Caution

Make sure to read the migration guide before updating to this version!

• [client] add run method to start the webhook server and listen for updates
• [server] refactor webhook handling to include validation and improve endpoint management
• [user] make profile temporary optional for testing
• [utils] add start_ngrok_tunnel function to facilitate local webhook testing
• [templates] enhance duplicate method to include target_waba_id parameter for template creation
• [templates] add validation for URL variables in URLButton to enforce constraints on example and variable usage

Full Changelog: 4.0.0b5...4.0.0b6

4.0.0b5

What's Changed

Update with pip: pip install -U pywa --pre
Updated Docs: pywa.readthedocs.io/en/dev/

Caution

Make sure to read the migration guide before updating to this version!

• [client] add methods for creating and verifying phone numbers on WhatsApp Business Account
• [templates] enhance Template and TemplateDetails with new methods for component retrieval and validation
• [templates] add param_names property for introspection of named parameters
• [templates] enhance error handling for positional and named examples in HeaderText and BodyText
• [templates] enhance CreativeFeaturesSpec with new attributes for improved media handling and text optimization
• [templates] remove TemplateSubCategory class and update sub_category type to string
• [message] fix reply to message in EditedMessage and DeletedMessage

Full Changelog: 4.0.0b4...4.0.0b5