Common methods

Common methods#

class pywa.types.base_update.BaseUpdate#

Base class for all update types.

abstract property id: str#: The id of the update

abstract property timestamp: datetime#: The timestamp the update was sent

stop_handling() → None#

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

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(...)

>>> @wa.on_message()
... def callback(_: WhatsApp, msg: Message):
...     msg.reply_text("Hello from PyWa!")
...     msg.stop_handling()

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

class pywa.types.base_update.BaseUserUpdate#

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

property sender: str#: The WhatsApp ID of the sender. - Shortcut for .from_user.wa_id.

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.

Reply to the message with text.

Shortcut for send_message() with to and reply_to_message_id.

Example

>>> msg.reply_text(
...     text="Hello from PyWa! (https://github.com/david-lev/pywa)",
...     quote=True,
... )

Example with keyboard buttons:

>>> from pywa.types import Button
>>> msg.reply_text(
...     header="Hello from PyWa!",
...     text="What can I help you with?",
...     footer="Powered by PyWa",
...     buttons=[
...         Button("Help", data="help"),
...         Button("About", data="about"),
...     ],
...     quote=True
... )

Example with a section list:

>>> from pywa.types import SectionList, Section, SectionRow
>>> msg.reply_text(
...     header="Hello from PyWa!",
...     text="What can I help you with?",
...     footer="Powered by PyWa",
...     buttons=SectionList(
...         button_title="Choose an option",
...         sections=[
...             Section(
...                 title="Help",
...                 rows=[
...                     SectionRow(
...                         title="Help",
...                         callback_data="help",
...                         description="Get help with PyWa",
...                     ),
...                     SectionRow(
...                         title="About",
...                         callback_data="about",
...                         description="Learn more about PyWa",
...                     ),
...                 ],
...            ),
...            Section(
...                 title="Other",
...                 rows=[
...                     SectionRow(
...                         title="GitHub",
...                         callback_data="github",
...                         description="View the PyWa GitHub repository",
...                     ),
...                 ],
...             ),
...         ],
...     ),
...     quote=True
... )

Parameters:

text – The text to reply with (markdown allowed, max 4096 characters).
header – The header of the reply (if buttons are provided, optional, up to 60 characters, no markdown allowed).
footer – The footer of the reply (if buttons are provided, optional, up to 60 characters, markdown has no effect).
buttons – The buttons to send with the message (optional).
quote – Whether to quote the replied message (default: False).
preview_url – Whether to show a preview of the URL in the message (if any).
keyboard – Deprecated and will be removed in a future version, use buttons instead.
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

Reply to the message with an image.

Shortcut for send_image() with to and reply_to_message_id.
Images must be 8-bit, RGB or RGBA.

Example

>>> msg.reply_image(
...     image="https://example.com/image.png",
...     caption="This is an image!",
...     quote=True,
... )

Parameters:

image – 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 – The caption of the image (required when buttons are provided, markdown allowed).
footer –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons – The buttons to send with the image (optional).
mime_type – 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 – Whether to quote the replied message (default: False).
body – Deprecated and will be removed in a future version, use caption instead.
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

Reply to the message with a video.

Shortcut for send_video() with to and reply_to_message_id.
Only H.264 video codec and AAC audio codec is supported.
Videos with a single audio stream or no audio stream are supported.

Example

>>> msg.reply_video(
...     video="https://example.com/video.mp4",
...     caption="This is a video",
...     quote=True,
... )

Parameters:

video – 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 –
The caption of the video (required when sending a video with buttons, markdown allowed).
footer –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons – The buttons to send with the video (optional).
mime_type – 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 – Whether to quote the replied message (default: False).
body – Deprecated and will be removed in a future version, use caption instead.
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

Reply to the message with a document.

Shortcut for send_document() with to and reply_to_message_id.

Example

>>> msg.reply_document(
...     document="https://example.com/example_123.pdf",
...     filename="example.pdf",
...     caption="Example PDF",
...     quote=True,
... )

Parameters:

document – 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 – The filename of the document (optional, The extension of the filename will specify what format the document is displayed as in WhatsApp).
caption –
The caption of the document (required when sending a document with buttons, markdown allowed).
footer –
The footer of the message (if buttons are provided, optional, markdown has no effect).
buttons – The buttons to send with the document (optional).
mime_type – 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).
body – Deprecated and will be removed in a future version, use caption instead.
quote – Whether to quote the replied message (default: False).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

Reply to the message with an audio.

Shortcut for send_audio() with to and reply_to_message_id.

Example

>>> msg.reply_audio(
...     audio='https://example.com/audio.mp3',
... )

Parameters:

audio – The audio file to reply with (either a media ID, URL, file path, bytes, or an open file object).
mime_type – The mime type of the audio (optional, required when sending a audio as bytes or a file object, or file path that does not have an extension).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent message.

Reply to the message with a sticker.

Shortcut for send_sticker() with to and reply_to_message_id.
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.

Example

>>> msg.reply_sticker(
...     sticker='https://example.com/sticker.webp',
... )

Parameters:

sticker – The sticker to reply with (either a media ID, URL, file path, bytes, or an open file object).
mime_type – 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 – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

reply_location(latitude: float, longitude: float, name: str | None = None, address: str | None = None, tracker: CallbackDataT | None = None) → str#

Reply to the message with a location.

Shortcut for send_location() with to and reply_to_message_id.

Example

>>> msg.reply_location(
...     latitude=37.4847483695049,
...     longitude=--122.1473373086664,
...     name='WhatsApp HQ',
...     address='Menlo Park, 1601 Willow Rd, United States',
... )

Parameters:

latitude – The latitude of the location.
longitude – The longitude of the location.
name – The name of the location (optional).
address – The address of the location (optional).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

reply_contact(contact: Contact | Iterable[Contact], quote: bool = False, tracker: CallbackDataT | None = None) → str#

Reply to the message with a contact/s.

Shortcut for send_contact() with to and reply_to_message_id.

Example

>>> from pywa.types import Contact
>>> 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 – The contact/s to send.
quote – Whether to quote the replied message (default: False).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

react(emoji: str, tracker: CallbackDataT | None = None) → str#

React to the message with an emoji.

Shortcut for send_reaction() with to and message_id.

Example

>>> msg.react('👍')

Parameters:

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

Returns:

The ID of the sent reaction.

unreact(tracker: CallbackDataT | None = None) → str#

Remove the reaction from the message.

Shortcut for remove_reaction() with to and message_id.

Example

>>> msg.unreact()

Parameters:: tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).
Returns:: The ID of the sent unreaction.

reply_catalog(body: str, footer: str | None = None, thumbnail_product_sku: str | None = None, quote: bool = False, tracker: CallbackDataT | None = None) → str#

Reply to the message with a catalog.

Shortcut for send_catalog() with to and reply_to_message_id.

Example

>>> msg.reply_catalog(
...     body='This is a catalog',
...     footer='Powered by PyWa',
...     thumbnail_product_sku='SKU123',
... )

Parameters:

body – Text to appear in the message body (up to 1024 characters).
footer – Text to appear in the footer of the message (optional, up to 60 characters).
thumbnail_product_sku – 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 – Whether to quote the replied message (default: False).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

reply_product(catalog_id: str, sku: str, body: str | None = None, footer: str | None = None, quote: bool = False, tracker: CallbackDataT | None = None) → str#

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().

Parameters:

catalog_id – 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 – The product SKU to send.
body – Text to appear in the message body (up to 1024 characters).
footer – Text to appear in the footer of the message (optional, up to 60 characters).
quote – Whether to quote the replied message (default: False).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

reply_products(catalog_id: str, product_sections: Iterable[ProductsSection], title: str, body: str, footer: str | None = None, quote: bool = False, tracker: CallbackDataT | None = None) → str#

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().

Example

>>> from pywa.types import ProductsSection
>>> 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 –
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 – The product sections to send (up to 30 products across all sections).
title – The title of the product list (up to 60 characters).
body – Text to appear in the message body (up to 1024 characters).
footer – Text to appear in the footer of the message (optional, up to 60 characters).
quote – Whether to quote the replied message (default: False).
tracker – The data to track the message with (optional, up to 512 characters, for complex data You can use CallbackData).

Returns:

The ID of the sent reply.

reply_template(template: Template, quote: bool = False, tracker: CallbackDataT | None = None) → str#

Reply to the message with a template.

– Shortcut for send_template() with to and reply_to_message_id.

Example

>>> from pywa.types import Template as Temp
>>> wa = WhatsApp(...)
>>> wa.send_template(
...     to='1234567890',
...         template=Temp(
...         name='buy_new_iphone_x',
...         language=Temp.Language.ENGLISH_US,
...         header=Temp.TextValue(value='15'),
...         body=[
...             Temp.TextValue(value='John Doe'),
...             Temp.TextValue(value='WA_IPHONE_15'),
...             Temp.TextValue(value='15%'),
...         ],
...         buttons=[
...             Temp.UrlButtonValue(value='iphone15'),
...             Temp.QuickReplyButtonData(data='unsubscribe_from_marketing_messages'),
...             Temp.QuickReplyButtonData(data='unsubscribe_from_all_messages'),
...         ],
...     ),
... )

Example for Authentication Template:

>>> from pywa.types import Template as Temp
>>> msg.reply_template(
...     template=Temp(
...         name='auth_with_otp',
...         language=Temp.Language.ENGLISH_US,
...         buttons=Temp.OTPButtonCode(code='123456'),
...     ),
...     quote=True
... )

Parameters:

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

Returns:

The ID of the sent reply.

Raises:

mark_as_read() → bool#

Mark the message as read.

Shortcut for mark_message_as_read() with message_id.

Returns:: Whether it was successful.

Common methods

Contents

Common methods#