Skip to content
PaalChat Docs

Common workflows

Media

Receive customers' photos, documents and voice notes, and send files - stored by PaalChat, fetched through short-lived links.

.md

In a nutshell

PaalChat downloads every incoming attachment from Meta and stores it (message.received has its media_id; media.updated follows with a 15-minute link). To send a file, upload it, then send an image, video, audio or document message with its media.id - inside the 24-hour window. Media is enabled per business.

Media is enabled per business by PaalTech. Without it, message.received still carries Meta's own media object, but PaalChat does not fetch the file, and uploads and media sends are refused with feature_disabled.

Receiving

  1. A customer sends a photo, document, voice note, video or sticker. message.received arrives with type (image, document...) and media_id - PaalChat's copy, pending for now.
  2. PaalChat downloads the file from Meta (Meta's links last only minutes), checks its size and SHA-256 and stores it privately.
  3. media.updated arrives with status: stored and a signed url. Fetch the bytes from it - no token needed - and keep them if you need them. If Meta would not give the file, status is failed with an error.

The url expires after 15 minutes. For a fresh one, call Get media. Never store or share the link itself; it is the credential.

cURL
curl -L -o photo.jpg "$MEDIA_URL"

Sending

  1. Upload media - multipart/form-data with a file field:

    cURL
    curl -X POST https://whatsapp.paaltech.org/api/v1/businesses/presec/media \
  -H "Authorization: Bearer $PAALCHAT_TOKEN" -F file=@receipt.pdf

  2. Send message with the matching type and the media.id:

    JSON
    {"to": "233241234567", "type": "document", "reference": "receipt-5521",
 "media": {"id": 12, "caption": "Your receipt", "filename": "receipt.pdf"}}

Like free-form text, media goes only inside the 24-hour customer service window; outside it, send a template. An uploaded file can be sent as often as you like.

Type Files Up to caption filename
image JPEG, PNG 5 MB yes -
video MP4, 3GP 16 MB yes -
audio AAC, AMR, MP3, M4A, OGG 16 MB - -
document PDF, Word, Excel, PowerPoint, text 100 MB yes yes

The type is detected from the file itself, not its name. A file that does not suit the message type is refused with media_type_mismatch; one WhatsApp cannot send at all with unsupported_media.

How long files are kept

Files are deleted with the conversation history, after 365 days by default (see the FAQ). The media record stays, with status: deleted.