Media Handling with wacli

wacli provides functionalities for both downloading media from synced messages and sending media files to chats. This page details how to use these features.

Downloading Media

When wacli synchronizes message history (via wacli auth or wacli sync), it primarily stores message metadata, including information about media attachments (images, videos, audio, documents). By default, the actual media files are not downloaded during sync to save local storage and bandwidth. However, wacli allows you to download these files on demand.

wacli media download

This command is used to download a specific media attachment associated with a synced message.

Usage:

Flags:

• --chat <chat-jid> (Required): The Jabber ID (JID) of the chat where the message containing the media was sent. Examples: [email protected] for a direct message, or [email protected] for a group.
• --id <message-id> (Required): The unique ID of the message that contains the media attachment. You can find this ID using wacli messages list or wacli messages search.
• --output <path> (Optional): Specifies where to save the downloaded file.
  • If a directory path is provided (ending with / or recognized as a directory), the file will be saved inside that directory using its default filename.
  • If a file path is provided, the media will be saved directly to that specified path and filename.
  • If omitted, wacli defaults to saving media in a structured path within your ~/.wacli store directory: ~/.wacli/media/<chat_jid>/<message_id>/<media_type>/<filename>.

Default Local Storage Path

For instance, an image from chat [email protected] with message ID ABC123DEF456 might be stored at: ~/.wacli/media/123_s.whatsapp.net/ABC123DEF456/image/picture.jpg

Example:

To download an image from a chat:

Background Media Download During Sync

You can configure wacli sync or wacli auth to automatically download media files in the background as they are synced:

When --download-media is enabled, wacli will enqueue media downloads for newly synced messages. Downloads happen asynchronously in worker goroutines, attempting to save media to the default local storage path.

Sending Media

wacli supports sending various file types as WhatsApp messages.

wacli send file

This command allows you to send an image, video, audio, or document file.

Usage:

Flags:

• --to <recipient> (Required): The recipient's phone number (e.g., 1234567890) or JID (e.g., [email protected] for DMs, [email protected] for groups).
• --file <path-to-file> (Required): The local path to the file you want to send.
• --caption <text> (Optional): A text caption to accompany the media. This is typically used for images, videos, and documents.
• --mime <mime-type> (Optional): Overrides the automatically detected MIME type of the file. wacli attempts to detect the MIME type based on the file extension and content. If detection fails or you need to send with a specific MIME type, you can use this flag (e.g., --mime application/pdf).

MIME Type Detection

wacli determines the media type (image, video, audio, document) and MIME type in the following order:

1. Uses the --mime flag value if provided.
2. Infers MIME type from the file extension.
3. Sniffs the file content to detect MIME type. Based on the detected MIME type, it then decides the WhatsApp media message type to use (e.g., ImageMessage, VideoMessage).

Example:

To send a picture with a caption:

To send a PDF document:

Refer to the [Getting Started] page for more general information on wacli usage and installation.