Common methods

Common methods#

class pywa.types.base_update.BaseUpdate#

Base class for all webhook updates.

id: str#: The WhatsApp Business Account ID for the business that is subscribed to the webhook.

timestamp: datetime.datetime#: Timestamp indicating when the WhatsApp server received the message from the customer (in UTC).

raw: RawUpdate#: The raw update dict from WhatsApp.

stop_handling()#

Call this method to break out of the handler loop. other handlers will not be called.

Use continue_handling() to continue to the next handler in the handlers loop.

This method just raises StopHandling which is caught by the handler loop and breaks out of it.

Example

>>> from pywa import WhatsApp
>>> from pywa.types import Message
>>> wa = WhatsApp(continue_handling=True) # NOT THE DEFAULT BEHAVIOR!

>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_text("Hello from PyWa!")
...     msg.stop_handling() # overwrite the default `continue_handling` behavior

>>> @wa.on_message
... def callback_not_called(_: WhatsApp, msg: Message):
...     msg.reply_text("This message will not be sent")

Return type:: NoReturn

continue_handling()#

Call this method to continue to the next handler in the handlers loop.

Use stop_handling() to break out of the handler loop.

This method just raises ContinueHandling which is caught by the handler loop and continues the loop.

Example

>>> from pywa import WhatsApp
>>> from pywa.types import Message
>>> wa = WhatsApp(continue_handling=False)  # default behavior

>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_text("Hello from PyWa!")
...     msg.continue_handling() # overwrite the default `continue_handling` behavior

>>> @wa.on_message
... def callback_called(_: WhatsApp, msg: Message):
...     msg.reply_text("This message will be sent")

Return type:: NoReturn

class pywa.types.base_update.BaseUserUpdate#

Base class for all user-related update types (message, callback, etc.).

reply_text(text, header=None, footer=None, buttons=None, *, quote=False, preview_url=False, tracker=None)#

Reply to the message with text.

Shortcut for send_message() with to and reply_to_message_id.
Text messages are messages containing text and an optional link preview.
You can have the WhatsApp client attempt to render a preview of the first URL in the body text string, if it contains one. URLs must begin with http:// or https://. If multiple URLs are in the body text string, only the first URL will be rendered. If omitted, or if unable to retrieve a link preview, a clickable link will be rendered instead.
See Text messages.
See Markdown for formatting text messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply(f"Hello {msg.from_user.name}! This is a reply to your message.", quote=True)

Parameters:

text (str) – The text to reply with (markdown allowed, max 4096 characters).
header (str | None) – The header of the reply (if buttons are provided, optional, up to 60 characters, no markdown allowed).
footer (str | None) – The footer of the reply (if buttons are provided, optional, up to 60 characters, markdown has no effect).
buttons (Iterable[Button] | URLButton | VoiceCallButton | CallPermissionRequestButton | SectionList | FlowButton | None) – The buttons to send with the message (optional).
quote (bool) – Whether to quote the replied message (default: False).
preview_url (bool) – Whether to show a preview of the URL in the message (if any).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_image(image, caption=None, footer=None, buttons=None, *, quote=False, mime_type=None, tracker=None)#

Reply to the message with an image.

Shortcut for send_image() with to and reply_to_message_id.
Image messages are messages that display a single image and an optional caption.
See Image messages.
See Supported image formats.
Images must be 8-bit, RGB or RGBA.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_image(
...         image="https://example.com/image.jpg",
...         caption="This is an image",
...     )

Parameters:

image (str | int | Media | pathlib.Path | bytes | BinaryIO) – The image to reply (either a media ID, URL, file path, bytes, or an open file object. When buttons are provided, only URL is supported).
caption (str | None) –
The caption of the image (required when buttons are provided, markdown allowed).
footer (str | None) –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | FlowButton | None) – The buttons to send with the image (optional).
mime_type (str | None) – The mime type of the image (optional, required when sending an image as bytes or a file object, or file path that does not have an extension).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_video(video, caption=None, footer=None, buttons=None, *, quote=False, mime_type=None, tracker=None)#

Reply to the message with a video.

Shortcut for send_video() with to and reply_to_message_id.
Video messages display a thumbnail preview of a video image with an optional caption. When the WhatsApp user taps the preview, it loads the video and displays it to the user.
Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only.
See Video messages.
See Supported video formats.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_video(
...         video="https://example.com/video.mp4",
...         caption="This is a video",
...     )

Parameters:

video (str | int | Media | pathlib.Path | bytes | BinaryIO) – The video to reply (either a media ID, URL, file path, bytes, or an open file object. When buttons are provided, only URL is supported).
caption (str | None) –
The caption of the video (required when sending a video with buttons, markdown allowed).
footer (str | None) –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | FlowButton | None) – The buttons to send with the video (optional).
mime_type (str | None) – The mime type of the video (optional, required when sending a video as bytes or a file object, or file path that does not have an extension).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_audio(audio, *, quote=False, mime_type=None, tracker=None)#

Reply to the message with an audio.

Shortcut for send_audio() with to and reply_to_message_id.
Audio messages display an audio icon and a link to an audio file. When the WhatsApp user taps the icon, the WhatsApp client loads and plays the audio file.
See Audio messages.
See Supported audio formats.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_audio(audio="https://example.com/audio.mp3")

Parameters:

audio (str | int | Media | pathlib.Path | bytes | BinaryIO) – The audio file to reply with (either a media ID, URL, file path, bytes, or an open file object).
quote (bool) – Whether to quote the replied message (default: False).
mime_type (str | None) – The mime type of the audio (optional, required when sending an audio as bytes or a file object, or file path that does not have an extension).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_document(document, filename=None, caption=None, footer=None, buttons=None, *, quote=False, mime_type=None, tracker=None)#

Reply to the message with a document.

Shortcut for send_document() with to and reply_to_message_id.
Document messages are messages that display a document icon, linked to a document, that a WhatsApp user can tap to download.
See Document messages.
See Supported document types.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_document(
...         document="https://example.com/document.pdf",
...         filename="document.pdf",
...         caption="This is a document",
...     )

Parameters:

document (str | int | Media | pathlib.Path | bytes | BinaryIO) – The document to reply (either a media ID, URL, file path, bytes, or an open file object. When buttons are provided, only URL is supported).
filename (str | None) – The filename of the document (optional, The extension of the filename will specify what format the document is displayed as in WhatsApp).
caption (str | None) –
The caption of the document (required when sending a document with buttons, markdown allowed).
footer (str | None) –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | FlowButton | None) – The buttons to send with the document (optional).
mime_type (str | None) – The mime type of the document (optional, required when sending a document as bytes or a file object, or file path that does not have an extension).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_location(latitude, longitude, name=None, address=None, *, quote=False, tracker=None)#

Reply to the message with a location.

Shortcut for send_location() with to and reply_to_message_id.
Location messages allow you to send a location’s latitude and longitude coordinates to a WhatsApp user.
Read more about Location messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_location(
...         latitude=37.4847483695049,
...         longitude=-122.1473373086664,
...         name='WhatsApp HQ',
...        address='Menlo Park, 1601 Willow Rd, United States',
...     )

Parameters:

latitude (float) – The latitude of the location.
longitude (float) – The longitude of the location.
name (str | None) – The name of the location (optional).
address (str | None) – The address of the location (optional).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_location_request(text, *, quote=False, tracker=None)#

Reply to the message with a request for the user’s location.

Shortcut for request_location() with to and reply_to_message_id.
Location request messages display body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can then use to share their location.
Once the user shares their location, a Message update is triggered, containing the user’s location details.
Read more about Location request messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_location_request(text='Please share your location')

Parameters:

text (str) – The text to send with the request.
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_contact(contact, *, quote=False, tracker=None)#

Reply to the message with a contact/s.

Shortcut for send_contact() with to and reply_to_message_id.
Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses. When a WhatsApp user taps the message’s profile arrow, it displays the contact’s information in a profile view:
Each message can include information for up to 257 contacts, although it is recommended to send fewer for usability and negative feedback reasons.
See Contacts messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_contact(
...         contact=Contact(
...             name=Contact.Name(formatted_name='David Lev', first_name='David'),
...             phones=[Contact.Phone(phone='1234567890', wa_id='1234567890', type='MOBILE')],
...             emails=[Contact.Email(email='test@test.com', type='WORK')],
...             urls=[Contact.Url(url='https://exmaple.com', type='HOME')],
...         ),
...         quote=True,
...     )

Parameters:

contact (Contact | Iterable[Contact]) – The contact/s to send.
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_sticker(sticker, *, quote=False, mime_type=None, tracker=None)#

Reply to the message with a sticker.

Shortcut for send_sticker() with to and reply_to_message_id.
Sticker messages display animated or static sticker images in a WhatsApp message.
A static sticker needs to be 512x512 pixels and cannot exceed 100 KB.
An animated sticker must be 512x512 pixels and cannot exceed 500 KB.
See Sticker messages.
See Supported sticker formats.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_sticker(sticker="https://example.com/sticker.webp")

Parameters:

sticker (str | int | Media | pathlib.Path | bytes | BinaryIO) – The sticker to reply with (either a media ID, URL, file path, bytes, or an open file object).
quote (bool) – Whether to quote the replied message (default: False).
mime_type (str | None) – The mime type of the sticker (optional, required when sending a sticker as bytes or a file object, or file path that does not have an extension).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_template(name, language, params, *, use_mm_lite_api=False, message_activity_sharing=None, quote=False, tracker=None)#

Reply to the message with a template.

Shortcut for send_template() with to and reply_to_message_id.
To create a template, use create_template().
Read more about Template Messages.

Parameters:

name (str) – The name of the template to send.
language (TemplateLanguage) – The language of the template to send.
params (list[BaseParams]) – The parameters to fill in the template.
use_mm_lite_api (bool) – Whether to use Marketing Messages Lite API (optional, default: False).
message_activity_sharing (bool | None) – Whether to share message activities (e.g. message read) for that specific marketing message to Meta to help optimize marketing messages (optional, only if use_mm_lite_api is True).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – A callback data to track the message (optional, can be a string or a CallbackData object).

Returns:

The sent template message.

Return type:

SentTemplate

reply_catalog(body, footer=None, *, thumbnail_product_sku=None, quote=False, tracker=None)#

Reply to the message with a catalog.

Shortcut for send_catalog() with to and reply_to_message_id.
Catalog messages are messages that allow you to showcase your product catalog entirely within WhatsApp.
Catalog messages display a product thumbnail header image of your choice, custom body text, a fixed text header, a fixed text sub-header, and a View catalog button.
When a customer taps the View catalog button, your product catalog appears within WhatsApp.
You must have inventory uploaded to Meta in an ecommerce catalog connected to your WhatsApp Business Account.
Read more about Catalog messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_catalog(
...         body='Check out our products!',
...         footer='Powered by PyWa',
...         thumbnail_product_sku='SKU123',  # Optional, if not provided,
...         # the first item in the catalog will be used.
...     )

Parameters:

body (str) – Text to appear in the message body (up to 1024 characters).
footer (str | None) – Text to appear in the footer of the message (optional, up to 60 characters).
thumbnail_product_sku (str | None) – The thumbnail of this item will be used as the message’s header image (optional, if not provided, the first item in the catalog will be used).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_product(catalog_id, sku, body=None, footer=None, *, quote=False, tracker=None)#

Reply to the message with a product.

Shortcut for send_product() with to and reply_to_message_id.
To reply with multiple products, use reply_products().
See Product messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_product(
...         catalog_id='1234567890',
...         sku='SKU123',
...         body='Check out this product!',
...         footer='Powered by PyWa',
...     )

Parameters:

catalog_id (str) – The ID of the catalog to send the product from. (To get the catalog ID use get_commerce_settings() or in the Commerce Manager).
sku (str) – The product SKU to send.
body (str | None) – Text to appear in the message body (up to 1024 characters).
footer (str | None) – Text to appear in the footer of the message (optional, up to 60 characters).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

reply_products(catalog_id, product_sections, title, body, footer=None, *, quote=False, tracker=None)#

Reply to the message with a product.

Shortcut for send_products() with to and reply_to_message_id.
To reply with multiple products, use reply_products().
See Product messages.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...    msg.reply_products(
...        catalog_id='1234567890',
...        title='Tech Products',
...        body='Check out our products!',
...        product_sections=[
...            ProductsSection(
...                title='Smartphones',
...                skus=['IPHONE12', 'GALAXYS21'],
...            ),
...            ProductsSection(
...                title='Laptops',
...                skus=['MACBOOKPRO', 'SURFACEPRO'],
...            ),
...        ],
...        footer='Powered by PyWa',
...        quote=True,
...    )

Parameters:

catalog_id (str) –
The ID of the catalog to send the product from (To get the catalog ID use get_commerce_settings() or in the Commerce Manager).
product_sections (Iterable[ProductsSection]) – The product sections to send (up to 30 products across all sections).
title (str) – The title of the product list (up to 60 characters).
body (str) – Text to appear in the message body (up to 1024 characters).
footer (str | None) – Text to appear in the footer of the message (optional, up to 60 characters).
quote (bool) – Whether to quote the replied message (default: False).
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message.

Return type:

SentMessage

react(emoji, *, tracker=None)#

React to the message with an emoji.

Shortcut for send_reaction() with to and message_id.
Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received.
When sending a reaction message, only a MessageStatus update (type set to SENT) will be triggered; DELIVERED and READ updates will not be triggered.
You can react to incoming messages by using the react() method on every update.
See Reaction messages.

Example:

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.react("👍")

Parameters:

emoji (str) – The emoji to react with.
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The sent message (You can’t use this message id to remove the reaction or perform any other action on it. instead, use the message ID of the message you reacted to).

Return type:

SentMessage

unreact(*, tracker=None)#

Remove the reaction from the message.

Shortcut for remove_reaction() with to and message_id.

You can remove reactions from incoming messages by using the unreact() method on every update.

See Reaction messages.

Example:
>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.react("👍")
...     msg.unreact()

= Args:

tracker: The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:: The sent message (You can’t use this message id to remove the reaction or perform any other action on it. instead, use the message ID of the message you reacted to).

Return type:: SentMessage

mark_as_read()#

Mark the message as read.

Shortcut for mark_message_as_read() with message_id.
You can mark incoming messages as read by using the mark_as_read() method or indicate typing by using the indicate_typing() method on every update.
It’s good practice to mark an incoming messages as read within 30 days of receipt. Marking a message as read will also mark earlier messages in the thread as read.
Read more about Mark messages as read.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.mark_as_read()

Returns:: Whether it was successful.
Return type:: SuccessResult

indicate_typing()#

Mark the message as read and display a typing indicator so the WhatsApp user knows you are preparing a response.

Shortcut for indicate_typing() with message_id.
The typing indicator will be dismissed once you respond, or after 25 seconds, whichever comes first. To prevent a poor user experience, only display a typing indicator if you are going to respond.
Read more about Typing indicators.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...     msg.indicate_typing()

Returns:: Whether it was successful.
Return type:: SuccessResult

call(sdp, *, tracker=None)#

Initiate a call with the user.

Shortcut for call() with to and message_id.
Read more at developers.facebook.com.

Example

>>> wa = WhatsApp(...)
>>> @wa.on_message
... def callback(_: WhatsApp, msg: Message):
...    msg.call(...)

Parameters:

sdp (SessionDescription) – The SDP object containing the call information.
tracker (str | CallbackData | None) – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The initiated call.

Return type:

InitiatedCall

property sender: str#: The Phone Number ID which the update was sent from.

property recipient: str#: The Phone Number ID which the update was sent to.

block_sender()#

Block the sender of the update.

Shortcut for block_users() with sender.

Return type:: bool

unblock_sender()#

Unblock the sender of the update.

Shortcut for unblock_users() with sender.

Return type:: bool

property message_id_to_reply: str#

The ID of the message to reply to.

If you want to wa.send_x with reply_to_message_id in order to reply to a message, use this property instead of id to prevent errors.

Common methods

Contents

Common methods#