Message

Message#

The Message type is used to represent incoming messages from WhatsApp user.

class pywa.types.Message#

A message received from a user.

‘Message’ on developers.facebook.com

Variables:

id – The message ID (If you want to reply to the message, use message_id_to_reply instead).
metadata – The metadata of the message (to which phone number it was sent).
type (MessageType) – The message type (See MessageType).
from_user – The user who sent the message.
chat (Chat) – The chat where the message was sent (private or group).
timestamp – The timestamp when the message was arrived to WhatsApp servers (in UTC).
reply_to_message (ReplyToMessage | None) – The message to which this message is a reply (if any).
forwarded (bool) – Whether the message was forwarded.
forwarded_many_times (bool) – Whether the message was forwarded more than 5 times. (when True, forwarded will be True as well)
text (str | None) – The text of the message.
image (Image | None) – The image of the message.
video (Video | None) – The video of the message.
sticker (Sticker | None) – The sticker of the message.
document (Document | None) – The document of the message.
audio (Audio | None) – The audio of the message.
voice – The voice note of the message (shorthand for audio if it’s a voice note).
caption – The caption of the message media (Optional, only available for image video and document messages).
reaction (Reaction | None) – The reaction of the message.
location (Location | None) – The location of the message.
contacts (ContactList | None) – The contacts of the message.
order (Order | None) – The order of the message.
referral (Referral | None) – The referral information of the message (When a customer clicks an ad that redirects to WhatsApp).
unsupported (Unsupported | None) – The unsupported content of the message.
error (WhatsAppError | None) – The error of the message.
shared_data – Shared data between handlers.

property has_media: bool#

Whether the message has any media. (image, video, sticker, document or audio)

If you want to get the media of the message, use media instead.

property is_reply: bool#

Whether the message is a reply to another message.

Reaction messages are also considered as replies (But .reply_to_message will be None).

The media of the message, if any, otherwise None. (image, video, sticker, document or audio)

If you want to check whether the message has any media, use has_media instead.

download_media(filepath=None, filename=None, *, chunk_size=None, **httpx_kwargs)#

Download the media of the message to the specified path.

Shortcut for message.media.download(...), message.image.download(...) etc.
Use get_media_bytes() if you want to get the file as bytes instead of saving it to disk.

>>> from pywa import WhatsApp, types, filters
>>> wa = WhatsApp(...)

>>> @wa.on_message(filters.image)
... def on_message(_: WhatsApp, msg: types.Message):
...     msg.download_media(path=pathlib.Path('/path/to/save'), filename='my_image.jpg')

Parameters:

filepath (str | None) – The path where to save the file (if not provided, the current working directory will be used).
filename (str | None) – The name of the file to save (if not provided, it will be extracted from the Content-Disposition header or a SHA256 hash of the URL will be used).
chunk_size (int | None) – The size (in bytes) of each chunk to read when downloading the media (default: 64KB).
**httpx_kwargs – Additional arguments to pass to httpx.get(...).

Returns:

The path of the saved file if in_memory is False, the file as bytes otherwise.

Raises:

ValueError – If the message does not contain any media.

Return type:

Path

stream_media(chunk_size=None, **httpx_kwargs)#

Stream the media of the message as bytes.

Shortcut for message.media.stream(...), message.image.stream(...) etc.
Use get_media_bytes() if you want to get the whole file as bytes.

>>> from pywa import WhatsApp, types, filters
>>> import httpx

>>> wa = WhatsApp(...)

>>> @wa.on_message(filters.document)
... def on_message(_: WhatsApp, msg: types.Message):
...     with httpx.Client() as client:
...        client.post('https://example.com/upload', content=msg.stream_media())

Parameters:

chunk_size (int | None) – The size (in bytes) of each chunk to read (default: 64KB).
**httpx_kwargs – Additional arguments to pass to httpx.get(...).

Returns:

An iterator that yields chunks of the media file as bytes.

Raises:

ValueError – If the message does not contain any media.

Return type:

Generator[bytes]

get_media_bytes(**httpx_kwargs)#

Get the media of the message as bytes.

Shortcut for message.media.get_bytes(...), message.image.get_bytes(...) etc.
Use stream_media() if you want to stream the file as bytes instead of getting it all at once.

>>> from pywa import WhatsApp, types, filters
>>> wa = WhatsApp(...)

>>> @wa.on_message(filters.document)
... def on_message(_: WhatsApp, msg: types.Message):
...     doc_bytes = msg.get_media_bytes()

Parameters:: **httpx_kwargs – Additional arguments to pass to httpx.get(...).
Returns:: The media file as bytes.
Raises:: ValueError – If the message does not contain any media.
Return type:: bytes

copy(to, header=None, body=None, footer=None, buttons=None, preview_url=False, reply_to_message_id=None, tracker=None, sender=None)#

Send the message to another user.

The WhatsApp Cloud API does not offer a real forward option, so this method will send a new message with the same content as the original message.

Supported message types: TEXT, DOCUMENT, IMAGE, VIDEO, STICKER, LOCATION, AUDIO, CONTACTS, ORDER and SYSTEM.

If the message type is reaction, you must provide reply_to_message_id.

Parameters:

to (str) – The phone ID of the WhatsApp user to copy the message to.
header (str | None) – The header of the message (if keyboard is provided, optional, up to 60 characters, no markdown allowed).
body (str | None) – The body/caption of the message (if buttons are provided, optional, up to 1024 characters, markdown allowed).
footer (str | None) – The footer of the message (if buttons is provided, optional, markdown has no effect).
buttons (Iterable[Button] | URLButton | VoiceCallButton | FlowButton | SectionList | None) – The buttons to send with the message (only in case of message from type text, document, video and image. also, the SectionList is only available to text type)
reply_to_message_id (str) – The message ID to reply to (optional).
preview_url (bool) – Whether to show a preview of the URL in the message (if any).
tracker (str | None) – The track data of the message.
sender (str | int | None) – The phone ID to send the message from (optional, overrides the client’s phone ID).

Returns:

The sent message.

Raises:

ValueError – If the message type is reaction and no reply_to_message_id is provided, or if the message type is unsupported.

Return type:

SentMessage

class pywa.types.MessageType#

Message types.

Variables:

TEXT – Message.text -> str.
IMAGE – Message.image -> Image.
VIDEO – Message.video -> Video.
DOCUMENT – Message.document -> Document.
AUDIO – Message.audio -> Audio.
STICKER – Message.sticker -> Sticker.
REACTION – Message.reaction -> Reaction.
LOCATION – Message.location -> Location.
CONTACTS – Message.contacts -> tuple[Contact].
ORDER – Message.order -> Order.
UNKNOWN – An unknown message (Warning with the actual type will be logged).
UNSUPPORTED – An unsupported message (message type not supported by WhatsApp Cloud API).
INTERACTIVE – Only used in CallbackButton, CallbackSelection and CallPermissionUpdate.
BUTTON – Only used in CallbackButton.
SYSTEM – Only used in PhoneNumberChange and IdentityChange

class pywa.types.User#

Represents a WhatsApp user.

Variables:

bsuid – The WhatsApp user’s BSUID. See developers.facebook.com for more information.
wa_id –
The user’s phone number in international format (without the ‘+’ sign). Will be unavailable if the user enables the username feature. See developers.facebook.com for more information.
name (str | None) – The name of the user.
username – The username of the user.
identity_key_hash (str | None) – The identity key hash of the user (Only if identity key check is enabled on the phone number settings).
parent_bsuid –
The Parent business-scoped user ID. See developers.facebook.com for more information.

block()#

Block the user.

Shortcut for block_users() with the user.

Returns:: True if the user was blocked
Return type:: bool
Raises:: BlockUserError – If the user was not blocked

unblock()#

Unblock the user.

Shortcut for unblock_users() with the user.

Returns:: True if the user was unblocked, False otherwise.
Return type:: bool

class pywa.types.Image#

Bases: ArrivedMedia

Represents a received image.

Variables:

id – The ID of the file (can be used to download or re-send the image).
sha256 – The SHA256 hash of the image.
mime_type – The MIME type of the image.
url – The URL of the image (Use get_bytes()/stream()/download() to access the image file).
caption (str | None) – The caption of the image.
uploaded_by – Who uploaded the image.
uploaded_at – The timestamp when the image was uploaded (in UTC).
uploaded_to – The phone ID the image was uploaded to (optional).

class pywa.types.Video#

Bases: ArrivedMedia

Represents a video.

Variables:

id – The ID of the file (can be used to download or re-send the video).
sha256 – The SHA256 hash of the video.
mime_type – The MIME type of the video.
url – The URL of the video (Use get_bytes()/stream()/download() to access the video file).
caption (str | None) – The caption of the video.
uploaded_by – Who uploaded the video.
uploaded_at – The timestamp when the video was uploaded (in UTC).
uploaded_to – The phone ID the video was uploaded to (optional).

class pywa.types.Audio#

Bases: ArrivedMedia

Represents an audio.

Variables:

id – The ID of the file (can be used to download or re-send the audio).
sha256 – The SHA256 hash of the audio.
mime_type – The MIME type of the audio.
voice (bool) – Whether the audio is a voice message or just an audio file.
url – The URL of the audio (Use get_bytes()/stream()/download() to access the audio file).
uploaded_by – Who uploaded the audio.
uploaded_at – The timestamp when the audio was uploaded (in UTC).
uploaded_to – The phone ID the audio was uploaded to (optional).

class pywa.types.Document#

Bases: ArrivedMedia

Represents a document.

Variables:

id – The ID of the file (can be used to download or re-send the document).
sha256 – The SHA256 hash of the document.
mime_type – The MIME type of the document.
filename – The filename of the document (optional).
url – The URL of the document (Use get_bytes()/stream()/download() to access the document file).
caption (str | None) – The caption of the document.
uploaded_by – Who uploaded the document.
uploaded_at – The timestamp when the document was uploaded (in UTC).
uploaded_to – The phone ID the document was uploaded to (optional).

class pywa.types.Sticker#

Bases: ArrivedMedia

Represents a sticker.

Variables:

id – The ID of the file (can be used to download or re-send the sticker).
sha256 – The SHA256 hash of the sticker.
mime_type – The MIME type of the sticker.
animated (bool) – Whether the sticker is animated.
url – The URL of the sticker (Use get_bytes()/stream()/download() to access the sticker file).
uploaded_by – Who uploaded the sticker.
uploaded_at – The timestamp when the sticker was uploaded (in UTC).
uploaded_to – The phone ID the sticker was uploaded to (optional).

class pywa.types.Reaction#

Represents a reaction to a message.

Variables:

message_id (str) – The ID of the message that was reacted to.
emoji (str | None) – The emoji that was used to react to the message (optional, None if removed).

property is_removed: bool#: Check if the reaction is removed.

class pywa.types.Location#

Represents a location.

Variables:

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).
url (str | None) – The URL of the location (optional).

property current_location: bool#: Check if the shared location is the current location or manually selected.

in_radius(lat, lon, radius)#

Check if the location is in a radius of another location.

Parameters:

lat (float) – The latitude of the other location.
lon (float) – The longitude of the other location.
radius (float | int) – The radius in kilometers.

Return type:

bool

class pywa.types.others.ContactList#

Bases: tuple[Contact, …]

Represents an shared contacts in a message, which can be iterated over to get the individual contacts.

Variables:: origin (pywa.types.others.ContactsOrigin) – The origin of the shared contacts (e.g. contact_request if the contacts were shared as a contact request, other otherwise).

property first: Contact#: Get the first contact in the list.

class pywa.types.others.ContactsOrigin#

Represents an origin of a contact.

Variables:

CONTACT_REQUEST – The contacts were shared as a contact request.
OTHER – The contacts were shared in another way.

class pywa.types.Contact#

Represents a contact.

Variables:

name (Name) – The name of the contact.
birthday (str | None) – The birthday of the contact (in YYYY-MM-DD format, optional).
phones (Iterable[Phone]) – The phone numbers of the contact.
emails (Iterable[Email]) – The email addresses of the contact.
urls (Iterable[Url]) – The URLs of the contact.
addresses (Iterable[Address]) – The addresses of the contact.
org (Org | None) – The organization of the contact (optional).

as_vcard()#

Get the contact as a vCard.

Return type:: str

class Name(formatted_name, first_name=None, last_name=None, middle_name=None, suffix=None, prefix=None)#

Represents a contact’s name.

At least one of the optional parameters needs to be included along with the formatted_name parameter.

Variables:

formatted_name (str) – The formatted name of the contact.
first_name (str | None) – The first name of the contact (optional).
last_name (str | None) – The last name of the contact (optional).
middle_name (str | None) – The middle name of the contact (optional).
suffix (str | None) – The suffix of the contact (optional).
prefix (str | None) – The prefix of the contact (optional).

class Phone(phone=None, type=None, wa_id=None)#

Represents a contact’s phone number.

Variables:

phone (str | None) – The phone number (If wa_id is provided, No need for the phone).
type (str | None) – The type of the phone number (Standard Values are CELL, MAIN, IPHONE, HOME, and WORK. optional).
wa_id (str | None) – The WhatsApp ID of the contact (optional).

class Email(email=None, type=None)#

Represents a contact’s email address.

Variables:

email (str | None) – The email address.
type (str | None) – The type of the email address (Standard Values are WORK and HOME. optional).

class Url(url=None, type=None)#

Represents a contact’s URL.

Variables:

url (str | None) – The URL.
type (str | None) – The type of the URL (Standard Values are WORK and HOME. optional).

class Org(company=None, department=None, title=None)#

Represents a contact’s organization.

Variables:

company (str | None) – The company of the contact (optional).
department (str | None) – The department of the contact (optional).
title (str | None) – The title of the business contact (optional).

class Address(street=None, city=None, state=None, zip=None, country=None, country_code=None, type=None)#

Represents a contact’s address.

Variables:

street (str | None) – The street number and name of the address (optional).
city (str | None) – The city name of the address (optional).
state (str | None) – State abbreviation.
zip (str | None) – Zip code of the address (optional).
country (str | None) – Full country name.
country_code (str | None) – Two-letter country abbreviation (e.g. US, GB, IN. optional).
type (str | None) – The type of the address (Standard Values are WORK and HOME. optional).

class pywa.types.Product#

Represents a product in an order.

Variables:

sku (str) – Unique identifier of the product in a catalog (also referred to as Content ID or Retailer ID).
quantity (int) – Number of items ordered.
price (float) – Price of the item.
currency (str) – Currency of the price.

property total_price: float#: Total price of the product.

class pywa.types.Order#

Represents an order.

Variables:

catalog_id (str) – The ID for the catalog the ordered item belongs to.
products (tuple[pywa.types.others.Product, ...]) – The ordered products.
text (str | None) – Text message from the user sent along with the order (optional).

Properties:: total_price: Total price of the order.

property total_price: float#: Total price of the order.

class pywa.types.Referral#

Represents a referral object in a message.

This object is included in the messages object when a customer clicks an ad that redirects to WhatsApp.

Variables:

source_url (str | None) – The Meta URL that leads to the ad or post clicked by the customer.
source_type (str | None) – The type of the ad’s source; ad or post.
source_id (str | None) – Meta ID for an ad or a post.
headline (str | None) – Headline used in the ad or post.
body (str | None) – Body for the ad or post.
media_type (str | None) – Media present in the ad or post; image or video.
image_url (str | None) – URL of the image, when media_type is an image.
video_url (str | None) – URL of the video, when media_type is a video.
thumbnail_url (str | None) – URL for the thumbnail, when media_type is a video.
ctwa_clid (str | None) – Click ID generated by Meta for ads that click to WhatsApp.

class pywa.types.Unsupported#

Represents an unsupported message.

Variables:: type (Literal['edit', 'poll', 'button']) – Contains the type of message that is unsupported (e.g., “edit”, “poll”, “button”).

class pywa.types.Metadata#

Represents the metadata of a message.

Variables:

display_phone_number (str) – The phone number to which the message was sent.
phone_number_id (str) – The ID of the phone number to which the message was sent.

class pywa.types.ReplyToMessage#

Represents a message that was replied to.

Variables:

id (str) – The ID of the message that was replied to.
from_user_id (str | None) – The ID of the user who sent the message that was replied to.
referred_product (pywa.types.others.ReferredProduct | None) – Referred product describing the product the user is requesting information about.

class pywa.types.ReferredProduct#

Represents a product this message is referring to.

Variables:

catalog_id (str)
sku (str) – Unique identifier of the product in a catalog (also referred to as Content ID or Retailer ID).

Message

Contents

Message#