[version] new version 3.0.0

Author: david-lev

CHANGELOG.md

@@ -3,6 +3,42 @@
 
 > NOTE: pywa follows the [semver](https://semver.org/) versioning standard.
 
+
+#### 3.0.0 (2025-08-22) **Latest**
+
+This release is a major update with significant improvements, new features, and some breaking changes.
+Please review the migration guide before upgrading.
+
+- [templates] Complete refactor of template support: creation, retrieval, sending, deleting, and status updates
+- [calls] Added full support for calls: making and receiving calls, call status updates, and call settings management
+- [user_preferences] Added full support for user preferences
+- [listeners] Unified listener handling with better safety checks
+- [system] Restructured system updates into `PhoneNumberChange` and `IdentityChange`
+- [client]
+  - `upload_media` now returns a `Media` object
+  - `mark_message_as_read` and other `update...` methods now return `SuccessResult` instead of `bool`
+  - New methods: `delete_media`, `get_business_phone_number_settings`, `update_business_phone_number_settings`, `update_display_name`, `get_business_account`, `deregister_phone_number`
+  - Support for mm-lite-api when sending templates
+  - Support for getting and setting `StorageConfiguration`
+- [callback]
+  - Added `is_quick_reply` to `CallbackButton`
+  - Stricter dataclass validation (no `kw_only`)
+- [updates]
+  - All user updates now include `waba_id`
+  - `Message` include new `referral` field
+- [types]
+  - Added `is_on_biz_app` to `BusinessPhoneNumber`
+  - `SuccessResult` introduced for extensibility
+- [security] Fixed XSS vulnerability
+- [api] `httpx.RequestError` now suggests providing a custom `httpx.Client`
+- [errors] Error messages are now more descriptive
+- [utils]
+  - Enum values handled case-sensitively
+  - Return `FlowRequestDecryptedMedia` object instead of raw tuple
+  - New `APIObject` helper for dataclasses
+- [deprecations] All previously deprecated attributes and types have been removed
+- [docs] New pywa logo 🚀
+
 #### 3.0.0-rc.3 (2025-08-06)
 
 - [templates] `params` is now can be called on class level
@@ -52,7 +88,7 @@
 - [deprecations] removed attrs and types marked as deprecated
 
 
-### 2.11.0 (2025-06-17) **Latest**
+### 2.11.0 (2025-06-17)
 
 - [flows] adding support for `ImageCarousel`
 - [flows] adding `with_params` to `FlowPreview` to configure the interactive web preview

MIGRATION.md

@@ -16,36 +16,47 @@
 
 ### New features
 
-- [templates] Refactored and improved templates support. The templates are now flexible, reusable, extensible, easier to use and more powerful.
-- [calls] Added full support for calls. You can now make and receive calls, manage calls, handle call events, configure call settings, and more.
-- [user_preferences] Added full support for user preferences. You can now listen to user marketing preferences - if the user has opted in or out of marketing messages, and act accordingly.
-- [server] Continued handling if listener is not using the update. If a listener does not use the update (not filtered or not cancelled), the server will continue to handle the update and pass it to the handlers.
-- [system] Moved `system` messages to `PhoneNumberChange` and `IdentityChange` updates. The `system` messages are now handled as separate updates, allowing you to focus on real user messages and events.
-- [client] Forced keyword-only for context args in `send_message`, `send_image`, and other `send_...` methods. This change improves readability and consistency of the API.
-- [types] Returned `SuccessResult` instead of `bool` to allow future extension with other attributes. The `SuccessResult` object acts as boolean, but can also contain additional information about the success of the operation.
-- [client] `upload_media` returns `Media` object. The `Media` object contains the media ID so you can use it later to send the media or perform other operations.
-- [client] Added `update_display_name` method to update the WhatsApp display name. This method allows you to change the display name of your WhatsApp account.
-- [handlers] Added `on_completion` decorator to flow request callback wrapper. This decorator allows you to register a callback that will be called when the flow request is completed.
-- [errors] Show more descriptive error messages. The error messages now provide more context and information about the error, making it easier to debug and fix issues.
-- [base_update] Added `waba_id` for all user updates. The `waba_id` is the WhatsApp Business Account ID that received the update, allowing you to identify the account that the update belongs to.
-- [message] Added `referral` field. When a customer clicks an ad that redirects to WhatsApp and starts a chat, the `referral` field contains information about the ad that was clicked.
-- [client] Added `delete_media` method. This method allows you to delete media files from WhatsApp servers.
+- [templates] Fully redesigned template system — now more flexible, reusable, and powerful.
+- [calls] Full support for calls: make/receive calls, manage call state, handle events, and configure settings.
+- [user_preferences] Full support for user marketing preferences (opt-in/out).
+- [listeners] Listeners can now wait for non-user updates (e.g., template approval, account events).
+- [system] System messages are now separate updates (`PhoneNumberChange`, `IdentityChange`).
+- [client]
+  - All `send_...` methods enforce keyword-only context args for clarity and consistency.
+  - `upload_media` now returns a `Media` object (with media ID).
+  - Added `delete_media` and `update_display_name` methods.
+- [handlers] Added `on_completion` decorator for flow request callbacks.
+- [types] `SuccessResult` replaces `bool`, extendable with extra attributes.
+- [base_update] All user updates now include `waba_id` (WhatsApp Business Account ID).
+- [message] New `referral` field (e.g., when users click ads leading to WhatsApp).
+- [errors] More descriptive error messages.
 
 
 ### Breaking changes
 
-- [templates] The templates system has been completely redesigned. The old templates are no longer supported, and you need to update your code to use the new templates system (create and send)
-- [listeners] Listeners can now be used to handle any update, not just user updates. This means that you can now use listeners to wait for template to be approved and to other account related upadtes. If you are using `wa.listen` directly (and not using one of the shortcuts like `wait_for_reply`, `wait_for_click` etc.), you will need to update your code to use the new listeners system.
-- [server] The server now continues to handle updates even if the listener does not use the update. This means that if a listener does not filter or cancel the update, the server will pass it to the handlers (unless you call `update.stop_handling()` inside the listener filters/cancelers).
-- [client] The `upload_media` method now returns a `Media` object instead of a string (media ID). The `Media` object contains the media ID and allows you to perform actions on the media, such as downloading or deleting it. If you using the media ID directly to send media - you don't need to change anything, just use the `Media` object instead of the string. if you stored the media ID in a database or somewhere else, you will need to update your code to use the `Media.id` attribute instead of the string media ID.
-- [client] The `send_message`, `send_image`, and other `send_...` methods now require keyword-only arguments for context. This change improves readability and consistency of the API. This context arguments are `reply_to_message_id`, `sender` etc. Most of users don't need to change anything, but if you are using positional arguments for these context args (they are located at the end of the method signature, so the chance for breaking is low), you will need to update your code to use keyword arguments.
-- [types] The `SuccessResult` object is now returned instead of a boolean value. This change allows for future extension of the `SuccessResult` object with additional attributes, such as error messages or additional information about the success of the operation. If you are using the return value of methods like `mark_as_read`, `indicate_typing`, etc., if you just checking if the operation was successful, you can continue to use it as a boolean. but if you storing the result in a database or forcing the result to be a boolean, you will need to update your code to use the `SuccessResult.success` attribute instead of the boolean value.
-- [system] The `system` messages are now handled as separate updates, and the `PhoneNumberChange` and `IdentityChange` updates are used instead. This change allows you to focus on real user messages and events, and handle system messages separately. If you were accessing the `system` attribute of the `Message` object, you will need to update your code to start listening to the `PhoneNumberChange` and `IdentityChange` updates instead.
-- [utils] The `FlowRequestDecryptedMedia` object is now returned instead of a tuple `(media_id, filename, data)`. This change allows you to access the media ID, filename, and data in a more structured way. If you were using the tuple to access the media ID, filename, and data, you will need to update your code to use the `FlowRequestDecryptedMedia` object instead.
+- [templates] Old template system removed. Update code to the new template APIs.
+- [listeners]
+  - Listeners apply to **all update types**, not just user messages.
+  - Legacy `to` parameter type updated.
+  - If using `wa.listen` directly, update to the new listener API (shortcuts like `wait_for_reply`, `wait_for_click` are unchanged).
+- [server] Updates now continue through the pipeline unless a listener explicitly cancels with `update.stop_handling()`.
+- [client]
+  - `upload_media` returns a `Media` object instead of a raw media ID string.
+    - If you only pass the `upload_media` result to `send_*` methods, no changes needed.
+    - If you store media IDs, update code to use `Media.id`.
+  - `send_message`, `send_image`, and other `send_...` methods now require keyword-only context args (`reply_to_message_id`, `sender`, etc.).
+    - Most users unaffected, but if you used positional args for these fields, switch to keywords.
+- [types] Methods like `mark_as_read`, `indicate_typing`, etc. now return `SuccessResult` instead of `bool`.
+  - Still usable in boolean checks (`if result:`).
+  - If you persist results or explicitly cast to `bool`, switch to `result.success`.
+- [system] `system` messages removed from `Message`. Listen to `PhoneNumberChange` and `IdentityChange` updates instead.
+- [utils] `FlowRequestDecryptedMedia` replaces raw `(media_id, filename, data)` tuple. Update code to use object attributes.
+
+---
 
 ### Migration steps
 
-1. If you are using the templates system, you need to update your code to use the new templates system. You can find the documentation for the new templates system [here](https://pywa.readthedocs.io/en/latest/content/templates/overview.html).
+1. Update all template usage to the new system ([docs here](https://pywa.readthedocs.io/en/latest/content/templates/overview.html)).
 
 ```python
 ########################## OLD CODE ##########################
@@ -139,57 +150,7 @@ wa.send_template(
 )
 ```
 
-2. If you are using the listeners system, you need to update your code to use the new listeners system. You can find the documentation for the new listeners system [here](https://pywa.readthedocs.io/en/latest/content/listeners/overview.html).
-
-```python
-########################## OLD CODE ##########################
-
-from pywa import WhatsApp, types, filters
-
-wa = WhatsApp(...)
-
-@wa.on_message(filters.text)
-def on_first_message(_: WhatsApp, msg: types.Message):
-    age = msg.reply(f"Hi {msg.from_user.name}! What's your age?").wait_for_reply(
-        # In the old code, if the update is not filtered, it will NOT be passed to the handlers (another_text_handler)
-        filters=filters.text & filters.new(lambda _, m: m.text.isdigit())
-    )
-    msg.reply(f"You are {age.text} years old!")
-
-
-@wa.on_message(filters.text)
-def another_text_handler(_: WhatsApp, msg: types.Message):
-    update = wa.listen(to="123456789", ...) # listen for updates from the user
-    ...
-
-########################## NEW CODE ##########################
-
-from pywa import WhatsApp, types, filters, listeners
-
-wa = WhatsApp(...)
-
-def filter_age(_: WhatsApp, msg: types.Message) -> bool:
-    if msg.text.isdigit():
-      return True # the update is filtered
-    msg.reply("Please enter a valid age (number).")
-    msg.stop_handling() # stop handling this update (will not be passed to the handlers)
-
-
-@wa.on_message(filters.text)
-def on_first_message(_: WhatsApp, msg: types.Message):
-    age = msg.reply(f"Hi {msg.from_user.name}! What's your age?").wait_for_reply(
-        # In the new code, if the update is not filtered, it will be passed to the handlers (another_text_handler), so we need to stop handling it if the age is not valid
-        filters=filters.text & filters.new(filter_age)
-    )
-    msg.reply(f"You are {age.text} years old!")
-
-@wa.on_message(filters.text)
-def another_text_handler(_: WhatsApp, msg: types.Message):
-    update = wa.listen(to=listeners.UserUpdateListenerIdentifier(sender="123456789", recipient="your_phone_id"), ...)  # listen for updates from the user
-    ...
-```
-
-3. If you are using the `upload_media` method, you need to update your code to use the `Media` object instead of a string (media ID):
+2. If you are using the `upload_media` method, you need to update your code to use the `Media` object instead of a string (media ID):
 
 ```python
 ########################## OLD CODE ##########################
@@ -218,73 +179,7 @@ cursor.execute("CREATE TABLE IF NOT EXISTS media (id INTEGER PRIMARY KEY AUTOINC
 cursor.execute("INSERT INTO media (media_id) VALUES (?)", (media.id,))
 ```
 
-4. If you are using the `send_message`, `send_image`, or other `send_...` methods, you need to update your code to use keyword-only arguments for context:
-
-```python
-########################## OLD CODE ##########################
-
-from pywa import WhatsApp, types
-
-wa = WhatsApp(...)
-
-wa.send_message(
-    "97234567890",
-    "Hello, World!",
-    "header text",
-    "footer text",
-    [types.Button(title="x", callback_data="y")],
-    True, # preview_url
-    "message_id", # reply_to_message_id
-    "phone_id", # sender
-)
-
-########################## NEW CODE ##########################
-
-from pywa import WhatsApp, types
-
-wa = WhatsApp(...)
-
-wa.send_message(
-    "97234567890",
-    "Hello, World!",
-    "header text",
-    "footer text",
-    [types.Button(title="x", callback_data="y")],
-    preview_url=True,  # kw only argument
-    reply_to_message_id="message_id",  # kw only argument
-    sender="phone_id",  # kw only argument
-)
-```
-
-5. If you are using the `SuccessResult` object, you need to update your code to use the `SuccessResult.success` attribute instead of a boolean value:
-
-```python
-########################## OLD CODE ##########################
-
-from pywa import WhatsApp, types
-
-wa = WhatsApp(...)
-
-result = wa.mark_as_read("97234567890", "message_id")
-
-# running sql query to store result
-cursor.execute("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, message_id VARCHAR UNIQUE NOT NULL, is_read BOOLEAN NOT NULL)")
-cursor.execute("INSERT INTO messages (message_id, is_read) VALUES (?, ?)", ("msg_id", result))
-
-########################## NEW CODE ##########################
-
-from pywa import WhatsApp, types
-
-wa = WhatsApp(...)
-
-result = wa.mark_as_read("97234567890", "message_id")
-
-# running sql query to store result.success
-cursor.execute("CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, message_id VARCHAR UNIQUE NOT NULL, is_read BOOLEAN NOT NULL)")
-cursor.execute("INSERT INTO messages (message_id, is_read) VALUES (?, ?)", ("msg_id", result.success))
-```
-
-6. If you are using the `system` messages, you need to update your code to start listening to the `PhoneNumberChange` and `IdentityChange` updates instead:
+3. If you are using the `system` messages, you need to update your code to start listening to the `PhoneNumberChange` and `IdentityChange` updates instead:
 
 ```python
 ########################## OLD CODE ##########################
@@ -317,37 +212,6 @@ def on_identity_change(_: WhatsApp, update: types.IdentityChange):
     repository.log_out_user(wa_id=update.sender)  # secure the user
 ```
 
-7. If you are using the `FlowRequestDecryptedMedia` object, you need to update your code to use the `FlowRequestDecryptedMedia` object instead of a tuple:
-
-```python
-########################## OLD CODE ##########################
-
-from pywa import WhatsApp, types
-
-wa = WhatsApp(...)
-
-@wa.on_flow_request("/my-flow-endpoint")
-def my_flow_endpoint(_: WhatsApp, req: types.FlowRequest):
-    media_id, filename, decrypted_data = req.decrypt_media(key="driver_license", index=0)
-    with open(filename, "wb") as file:
-        file.write(decrypted_data)
-    return req.respond(...)
-
-########################## NEW CODE ##########################
-
-from pywa import WhatsApp, types
-
-wa = WhatsApp(...)
-
-@wa.on_flow_request("/my-flow-endpoint")
-def my_flow_endpoint(_: WhatsApp, req: types.FlowRequest):
-    decrypted_media = req.decrypt_media(key="driver_license", index=0)
-    with open(decrypted_media.filename, "wb") as file:
-        file.write(decrypted_media.data)
-    return req.respond(...)
-```
-
-
 ## Migration from 1.x to 2.x
 
 

pywa/__init__.py

@@ -9,6 +9,6 @@
 from pywa.client import WhatsApp
 from pywa.utils import Version
 
-__version__ = "3.0.0-rc.3"
+__version__ = "3.0.0"
 __author__ = "David Lev"
 __license__ = "MIT"