How to Send Files with Custom Display Filenames in wacli

Use the --filename flag in wacli send file to specify a custom display name while the actual file path remains used for MIME detection and content hashing.

The wacli command-line tool for WhatsApp automation, maintained in the steipete/wacli repository, supports sending files with custom display filenames. This feature allows you to present a different name to recipients than the actual file stored on disk, which is particularly useful for renaming reports, masking temporary filenames, or standardizing document titles across your organization.

Understanding the --filename Flag

The --filename flag is defined in the CLI layer at cmd/wacli/send_file_cmd.go (lines 69-71). When you invoke wacli send file, this flag captures your custom display name and passes it through the application layers to the WhatsApp message constructor.

If you omit the flag, wacli automatically uses the basename of the file path specified in --file as the display name.

How wacli Processes Custom Display Filenames

CLI Flag Parsing and Propagation

In cmd/wacli/send_file_cmd.go, the --filename value is stored in a local variable and passed to the sendFile helper function (lines 49-51). The function signature accepts this as a distinct filename parameter, separating the display name concerns from the physical file path.

Name Resolution Logic

Inside cmd/wacli/send_file.go (lines 29-33), the sendFile function implements the resolution logic:

• If filename is non-empty after trimming, it becomes the name variable
• If empty, name defaults to the basename of the actual file path

This name variable represents the final display name that recipients see in their WhatsApp client.

WhatsApp Protobuf Construction

For document-type uploads, the resolved name is injected into the WhatsApp protocol buffer at cmd/wacli/send_file.go (lines 1010-1014). The code sets both FileName and Title fields of waProto.DocumentMessage to the custom display name.

These fields control what appears as the document title in the recipient's chat interface, while the actual file content and MIME type detection use the original --file path.

Local Storage Persistence

After successful transmission, wacli persists the custom filename in the local SQLite database via UpsertMessage in internal/store/messages.go (lines 21-22 and 33-35). The database schema includes a dedicated filename column added in migration version 2, defined in internal/store/migrations.go (lines 132-134).

This allows message history queries to display the correct custom filename even if the original file has been moved or renamed on disk.

Practical Code Examples

Send a quarterly report with a standardized display name while keeping the original filename for internal tracking:

wacli send file \
    --to 15551234567 \
    --file ./reports/2024-Q1-draft-final-v3.pdf \
    --filename "Q1-2024-Report.pdf" \
    --caption "Quarterly performance summary"

JSON output (using --json flag):

{
  "sent": true,
  "to": "[email protected]",
  "id": "ABCD1234EFGH5678",
  "file": {
    "name": "Q1-2024-Report.pdf",
    "mime_type": "application/pdf",
    "media": "document"
  }
}

Default text output:

Sent Q1-2024-Report.pdf to [email protected] (id ABCD1234EFGH5678)

The --filename flag works consistently across document, image, video, and audio uploads, though for media types the visible caption often takes precedence over the filename in the WhatsApp UI.

Summary

• Use --filename with wacli send file to set a custom display name independent of the source file path
• The actual file path (--file) drives MIME type detection and content hashing, while --filename populates the WhatsApp message metadata
• The custom name is stored in waProto.DocumentMessage.FileName and Title fields for document uploads
• Local SQLite persistence via UpsertMessage maintains the custom filename in the messages table for history tracking
• If --filename is omitted, wacli automatically uses the basename of the --file argument

Frequently Asked Questions

What happens if I don't specify the --filename flag?

If you omit the --filename flag, wacli extracts the basename from the --file path and uses that as the display name. This logic is implemented in cmd/wacli/send_file.go (lines 29-33), where the code checks if the filename parameter is empty and defaults to the file's basename.

Does the custom filename affect MIME type detection?

No. The custom filename provided via --filename is used exclusively for display purposes in the WhatsApp interface. MIME type detection and content hashing use the actual file path specified in --file. According to the source code in cmd/wacli/send_file.go, the display name is resolved separately from the media type detection logic.

Is the custom filename visible in message history?

Yes. When you send a file with a custom filename, wacli persists this name in the local SQLite database via the UpsertMessage function in internal/store/messages.go. The database schema includes a dedicated filename column (added in migration version 2), ensuring that message history queries display the correct custom filename even if the original file has been moved or renamed.

Can I use custom filenames for images and videos?

Yes, the --filename flag works for all media types including images, videos, and audio files. However, for these media types, the WhatsApp UI typically prioritizes the caption text over the filename in the display. The custom filename is still sent in the message metadata and stored in local history, but recipients may see the caption more prominently than the filename for non-document media.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}