# Media

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

> **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`](/docs/api/callbacks/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`](/docs/api/callbacks/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](/docs/api/get-media). Never store or share the link itself; it is the
credential.

```bash
curl -L -o photo.jpg "$MEDIA_URL"
```

## Sending

1. [Upload media](/docs/api/upload-media) - `multipart/form-data` with a `file` field:

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

2. [Send message](/docs/api/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](/docs/faq)). The media record stays, with `status: deleted`.