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

# Upload a WhatsApp header file

> Get a link to upload the image, video or document a WhatsApp template's header shows.

Plans with WhatsApp (Pro and up) can use this endpoint. On other plans it returns `403`.

Use it for a WhatsApp template whose header is an image, video or document. WhatsApp gets the header file from a link, and that link must point to Nedzo's storage. Get a link to upload one file. Then:

1. `PUT` the file bytes to `uploadUrl`, with the `Content-Type` header set to `contentType`.
2. Send the template with [Send a WhatsApp message](https://docs.nedzo.ai/api-reference/conversations/send-whatsapp.md), with `template.parameters.header` set to `{ "type": type, "link": link }` from this answer. Add `filename` for a document.

The upload link works for 2 hours. Each link puts the file at a new address, so it can't replace another file. The file stays after the link ends, so you can send one upload as many times as you like.

| Extension | `contentType` | Header `type` | Largest file |
| - | - | - | - |
| `jpg`, `jpeg` | `image/jpeg` | `image` | 5 MB |
| `png` | `image/png` | `image` | 5 MB |
| `mp4` | `video/mp4` | `video` | 16 MB |
| `pdf` | `application/pdf` | `document` | 16 MB |

The link fixes the address, not the file type or size. Send the `contentType` from this answer when you upload. A file of another type, or one over the size limit, uploads, but the send refuses it with `400`.

Anyone with the `link` can open the file.

> [!TIP]
>
> `workspaceId` is required when your account has more than one workspace. See [Workspace ID and Request Scope](https://docs.nedzo.ai/authentication#workspace-id-and-request-scope).

## Body Parameters

**workspaceId** `string`

The workspace. Required when your account has more than one workspace.

**fileName** `string` *required*

The file name, with its extension: `.jpg`, `.jpeg`, `.png`, `.mp4` or `.pdf`. Up to 255 characters.

**contentType** `string` *required*

The file type from the table above. It must match the extension.

## Errors

| Status | When |
| - | - |
| `400` | The body is not valid, WhatsApp does not take this file type in a template header, or `fileName` does not have an extension for `contentType`. |
| `402` | The account has no plan in force. |
| `403` | Your plan does not include WhatsApp, or the workspace is locked. For a locked workspace the answer has `workspaceLocked: true`. |
| `404` | The workspace is not in your API key's scope. |
| `429` | Too many requests in a short time. Wait, then try again. |
| `502` | We could not check the workspace or create a link. Try again. |

```bash theme={null}
curl -X POST "https://api.nedzo.ai/v1/conversations/whatsapp/uploads" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "fileName": "spring-promo.png", "contentType": "image/png" }'

# Then upload the file to the uploadUrl from the answer
curl -X PUT "UPLOAD_URL" \
    -H "Content-Type: image/png" \
    --data-binary @spring-promo.png
```

```json Response (201) theme={null}
{
  "uploadUrl": "https://...",
  "method": "PUT",
  "link": "https://...",
  "type": "image",
  "fileName": "spring-promo.png",
  "contentType": "image/png",
  "maxBytes": 5242880,
  "expiresAt": "2026-11-13T12:00:00Z"
}
```


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