Media

Media#

class pywa.types.media.Media#

Base class for all media types.

Variables:

  • id (str) – The ID of the media.

  • uploaded_by (UploadedBy) – Who uploaded the media (business or user).

  • uploaded_at (datetime.datetime) – The timestamp when the media was uploaded (in UTC).

  • uploaded_to (str) – The phone ID the media was uploaded to.

property is_expired: bool#

Checks if the media is expired (30 days for business uploaded media, 7 days for user uploaded media).

property expires_at: datetime#

Gets the expiration date of the media.

property days_until_expiration: int#

Gets the number of days until the media expires.

get_media_url()#

Gets the URL of the media. (expires after 5 minutes)

Return type:

str

download(*, path=None, filename=None, in_memory=None, chunk_size=None, **httpx_kwargs)#

Download a media file from WhatsApp servers.

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

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

  • path (str | Path | 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.

Return type:

Path

delete(*, phone_id=<object object>)#

Deletes the media from WhatsApp servers.

Parameters:

phone_id (str | int | None) – The phone ID to delete the media from (optional, If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on. pass None to use the client’s phone ID).

Return type:

SuccessResult

reupload(*, to_phone_id=None, override_filename=None)#

Reuploads the media to WhatsApp servers.

  • Useful for re-sending media from another business phone number or if you want to use the media more than 30 days after it was uploaded.

Parameters:

  • to_phone_id (str | int | None) – The phone ID to upload the media to (if not provided, the client’s phone ID will be used).

  • override_filename (str | None) – The filename to use for the re-uploaded media (if not provided, the original filename will be used if available).

Return type:

Media

class pywa.types.media.ArrivedMedia#

Bases: Media

Base class for all media types that can be received in a message.

Variables:

  • id (str) – The ID of the file (can be used to download or re-send the media later, but only for 7 days after it was uploaded by the user).

  • sha256 (str) – The SHA256 hash of the media.

  • mime_type (str) – The MIME type of the media.

  • url (str | None) – The URL of the media (may be None in webhook versions before 24.0, use get_media_url() to get it).

  • uploaded_by (UploadedBy) – Who uploaded the media (always USER for arrived media).

  • uploaded_at (datetime.datetime) – The timestamp when the message containing the media was received (in UTC).

  • uploaded_to (str | None) – The phone ID the media was received to (optional when constructing manually).

property extension: str | None#

Gets the extension of the media (with dot.)

classmethod from_flow_completion(client, media)#

Create a media object from the media dict returned by the flow completion.

Example

>>> from pywa import WhatsApp, types
>>> wa = WhatsApp(...)
>>> @wa.on_flow_completion
... def on_flow_completion(_: WhatsApp, flow: types.FlowCompletion):
...     img = types.Image.from_flow_completion(client=wa, media=flow.response['media'])
...     img.download()
Parameters:

  • client (WhatsApp) – The WhatsApp client.

  • media (dict[str, str]) – The media dict returned by the flow completion.

Returns:

The media object (Image, Video, Sticker, Document, Audio).

Return type:

ArrivedMedia

class pywa.types.media.MediaURL#

Represents a media response.

  • The URL is valid for 5 minutes.

Variables:

  • id (str) – The ID of the media.

  • url (str) – The URL of the media (valid for 5 minutes).

  • mime_type (str) – The MIME type of the media.

  • sha256 (str) – The SHA256 hash of the media.

  • file_size (int) – The size of the media in bytes.

property expires_at: datetime#

Gets the expiration date of the media URL (5 minutes after creation).

property is_expired: bool#

Checks if the media URL is expired. If expired, you need to regenerate it.

download(*, path=None, filename=None, in_memory=None, chunk_size=None, **httpx_kwargs)#

Download a media file from WhatsApp servers.

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

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

  • path (str | Path | 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.

Return type:

Path

delete(*, phone_id=<object object>)#

Deletes the media from WhatsApp servers.

Parameters:

phone_id (str | int | None) – The phone ID to delete the media from (optional, If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on. pass None to use the client’s phone ID).

Return type:

SuccessResult

property minutes_until_expiration: int#

Gets the number of minutes until the media URL expires.

reupload(*, to_phone_id=None, override_filename=None)#

Reuploads the media to WhatsApp servers.

  • Useful for re-sending media from another business phone number or if you want to use the media more than 30 days after it was uploaded.

  • If the media URL is expired, it will use the media ID to reupload (Will make an extra request to get a new URL).

Parameters:

  • to_phone_id (str | int | None) – The phone ID to upload the media to (if not provided, the client’s phone ID will be used).

  • override_filename (str | None) – The filename to use for the re-uploaded media (if not provided, the original filename will be used if available).

Return type:

Media

regenerate_url()#

Regenerates the media URL.

  • The new URL will be valid for 5 minutes.

Returns:

The new MediaURL object.

Return type:

MediaURL

class pywa.types.media.UploadedBy#

Enum representing who uploaded the media.

Variables:

  • BUSINESS – The media was uploaded by the business (available for 30 days).

  • USER – The media was uploaded by a user (available for 7 days).

Contents