💬 Updates#

Updates are the incoming events from the WhatsApp Cloud API. They are sent to your webhook URL and converted by PyWa into type-safe objects that are easy to handle.

In WhatsApp Cloud API, updates are called fields, and you need to subscribe to them in order to receive them at your webhook URL.

Supported Fields#

The currently supported fields in PyWa are:

messages → all user-related updates (messages, callbacks, message status updates)
calls → call connect, terminate, and status updates
message_template_status_update → template approved, rejected, etc.
message_template_quality_update → template quality score changed
message_template_components_update → template components changed (header, body, footer, buttons)
template_category_update → template category changed
user_preferences → user marketing preferences

Tip

If you want to handle other types of updates, use on_raw_update() decorator or the RawUpdateHandler class.

from pywa import WhatsApp, types

wa = WhatsApp(...)

@wa.on_raw_update
def handle_raw_update(wa: WhatsApp, raw: dict):
    print("Received raw update:", raw)

Update Types#

The supported fields are automatically handled by PyWa and converted into Python classes.

👉 To learn how to handle them, see: Handlers

User-related updates:

Type	Description
`Message`	A message sent by a user (text, media, order, location, etc.)
`CallbackButton`	A `Button` \| `QuickReplyButton` pressed by a user
`CallbackSelection`	A `SectionRow` chosen by a user
`FlowCompletion`	A flow completed by a user
`MessageStatus`	A message status update (delivered, seen, etc.)
`ChatOpened`	A chat opened by a user
`PhoneNumberChange`	A user’s phone number changed
`IdentityChange`	A user’s identity changed
`CallConnect`	A call connected by a user
`CallTerminate`	A call terminated by a user
`CallStatus`	A call status update (ringing, busy, etc.)
`CallPermissionUpdate`	A call permission update (permission granted or denied)
`UserMarketingPreferences`	A user marketing preferences update (e.g. opted in, opted out)

Account-related updates:

Type	Description
`TemplateStatusUpdate`	A template status update (approved, rejected, etc.)
`TemplateCategoryUpdate`	A template category update (category changed)
`TemplateQualityUpdate`	A template quality update (quality score changed)
`TemplateComponentsUpdate`	A template components update (header, body, footer, buttons changed)

Common Properties#

All updates share common methods and properties:

Property	Description
`id`	The update ID
`raw`	The raw update data
`timestamp`	The update timestamp (UTC)
`stop_handling()`	Prevent further handlers from processing the update
`continue_handling()`	Force the update to continue to the next handler

User-related updates share additional properties:

Method / Property	Description
`sender`	The phone ID of the sender
`recipient`	The phone ID of the recipient
`message_id_to_reply`	The message ID to reply to
`reply_text()`	Reply with a text message
`reply_image()`	Reply with an image message
`reply_video()`	Reply with a video message
`reply_audio()`	Reply with an audio message
`reply_document()`	Reply with a document message
`reply_location()`	Reply with a location message
`reply_location_request()`	Request the user’s location
`reply_contact()`	Reply with a contact message
`reply_sticker()`	Reply with a sticker message
`reply_template()`	Reply with a template message
`reply_catalog()`	Reply with a catalog message
`reply_product()`	Reply with a product message
`reply_products()`	Reply with a list of product messages
`react()`	React to the update with an emoji
`unreact()`	Remove a reaction
`mark_as_read()`	Mark the update as read
`indicate_typing()`	Indicate typing to the user
`block_sender()`	Block the sender
`unblock_sender()`	Unblock the sender
`call()`	Start a call with the sender

💬 Updates

Contents

💬 Updates#

Supported Fields#

Update Types#

Common Properties#