Media#

class pywa.types.media.Media#

Base class for all media types.

Variables:

id (str) – The ID of the media.
filename (str | None) – The filename 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 (30 days for business uploaded media, 7 days for user uploaded media).

property days_until_expiration: int#: Gets the number of days until the media expires.

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

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

Download a media file from WhatsApp servers.

Same as download_media() with media_url=media.get_media_url()
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.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).
**httpx_kwargs – Additional arguments to pass to httpx.get(...).

Returns:

The path of the saved file.

Return type:

Path

get_bytes(**httpx_kwargs)#

Get the media file as bytes.

Same as get_media_bytes() with media_url=media.get_media_url()
Use stream() 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.document.get_bytes()

Parameters:: **httpx_kwargs – Additional arguments to pass to httpx.get(...).
Returns:: The media file as bytes.
Return type:: bytes

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 media owner’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

stream(chunk_size=None, **httpx_kwargs)#

Stream the media file as bytes.

Same as stream_media() with media_url=media.get_media_url()
Use get_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.document.stream())

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.

Return type:

Generator[bytes]

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).
filename (str | None) – The filename of the media (only for documents or when arrived via flow completion).
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.

You can use the shortcut get_media()

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.

property minutes_until_expiration: int#: Gets the number of minutes until the media URL expires.

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

Media

Contents

Media#