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.

• 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 (str | None) – The caption of the message (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 (tuple[Contact, ...] | 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).

property media: Image | Video | Sticker | Document | Audio | 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, in_memory=False, *, chunk_size=None, **httpx_kwargs)

Download a media file from WhatsApp servers (image, video, sticker, document or audio).

• Shortcut for message.media.download(...), message.image.download(...) etc.

• Use get_media_bytes() or stream_media() instead of in_memory=True.

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

• in_memory (None) – Deprecated: Use get_media_bytes() or stream_media() instead. If True, the file will be returned as bytes instead of being saved to disk.

• **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

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.

• REQUEST_WELCOME – Only used in ChatOpened.

• SYSTEM – Only used in PhoneNumberChange and IdentityChange

---

class pywa.types.User

Represents a WhatsApp user.

Variables:

• wa_id (str) – The WhatsApp ID of the user (The phone number with the country code).

• name (str | None) – The name of the user (None on MessageStatus).

• identity_key_hash (str | None) – The identity key hash of the user (Only if identity key check is enabled on the phone number settings).

block()

Block the user.

• Shortcut for block_users() with the user wa_id.

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 wa_id.

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.

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.

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.

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

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.

---

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.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.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:

• message_id (str) – The ID of the message that was replied to.

• from_user_id (str) – 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).