> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload WhatsApp media

> Upload media and use the returned media ID in WhatsApp message requests.

## What it is

The Media API uploads an image, video, audio file, sticker, or document through
the WhatsApp Business API. The returned media ID can be referenced by a later
WhatsApp message request.

## Before you begin

* Connect and register the sending WhatsApp phone number.
* Store your YCloud API key securely.
* Prepare a file that meets Meta's supported media type and size limits.
* Know whether the target message type supports a media ID or requires a URL.

## How it works

1. Upload the file for the sending phone number.
2. Store the returned media ID.
3. Put the media ID in the matching WhatsApp message content object.
4. Send the message before the uploaded media expires.

Uploaded files are encrypted and persist for 30 days.

## Request

`POST /whatsapp/media/{phoneNumber}/upload`

Send the file as `multipart/form-data`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/media/+16315551111/upload \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "file=@./invoice.pdf;type=application/pdf"
```

Use the registered business phone number in E.164 format.

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MEDIA_ID"
}
```

Store `id` and use it in the media object for a supported WhatsApp message
request.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice.pdf"
  }
}
```

## Media usage

A media ID is tied to WhatsApp media storage and expires after 30 days. Upload
again when the ID is no longer valid.

Interactive message headers cannot use a media ID for images, documents,
videos, or audio. Use a publicly accessible link for those header elements.

## Limits and troubleshooting

* Send the correct MIME type with the uploaded file.
* Check Meta's supported media types and size limits before uploading.
* Do not reuse an expired media ID.
* Keep the upload and message sender phone number aligned.
* For reusable public assets, a link may be simpler than repeated uploads when
  the message schema supports it.

<CardGroup cols={2}>
  <Card title="Upload media API" icon="upload" href="/api-reference/whatsapp-media/upload-media">
    Inspect the multipart request and response schema.
  </Card>

  <Card title="Send media messages" icon="image" href="/en/api-reference/guides/whatsapp-platform/send-whatsapp-message">
    Add the returned media ID to a WhatsApp message request.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.