> For the complete documentation index, see [llms.txt](https://docs.channel360.co.za/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.channel360.co.za/api-usage/reply-to-a-customer/upload-a-file.md).

# Upload a file

Get a public link for a file you want to send in a media reply, when you cannot host it yourself.

A media reply needs the file at a public `https://` link. This endpoint uploads a file and gives you that link, ready to use as `mediaUrl` in a [media reply](https://docs.channel360.co.za/api-usage/reply-to-a-customer/send-a-media-reply.md).

{% hint style="warning" %}
**Host your files yourself where you can.** The recommended approach is to serve files from your own storage, such as your website, a storage bucket or a content delivery network, and pass that link as `mediaUrl`. You stay in control of the file, its lifetime and who can reach it.

This endpoint is intended for **testing and integration development**, and as a **fallback** when hosting the file yourself is not possible. It is not a long-term file store.
{% endhint %}

## Before you start

* An API key and your Organisation API URL. See [Authentication](https://docs.channel360.co.za/api-usage/get-started/authentication.md).
* The file, no larger than **20 MB**. It must be a type WhatsApp accepts for the message you plan to send. See [Send a media reply](https://docs.channel360.co.za/api-usage/reply-to-a-customer/send-a-media-reply.md).

## Upload the file

`POST` `/org/<ORG_ID>/whatsapp/attachments`

```
https://channel360.co.za/v1.1/org/<ORG_ID>/whatsapp/attachments
```

Send the request as `multipart/form-data`, with the file in a field named **`source`**. Send one file per request.

{% hint style="info" %}
Do not set the `Content-Type` header yourself. Your HTTP client sets it, including the multipart boundary, when it builds the form.
{% endhint %}

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST "https://channel360.co.za/v1.1/org/<ORG_ID>/whatsapp/attachments" \
  -H "Authorization: Bearer <API_KEY>" \
  -F "source=@september-invoice.pdf"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append(
  "source",
  new Blob([await readFile("september-invoice.pdf")], { type: "application/pdf" }),
  "september-invoice.pdf"
);

const response = await fetch(
  "https://channel360.co.za/v1.1/org/<ORG_ID>/whatsapp/attachments",
  {
    method: "POST",
    headers: { Authorization: "Bearer <API_KEY>" },
    body: form
  }
);

console.log(await response.json());
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

with open("september-invoice.pdf", "rb") as file:
    response = requests.post(
        "https://channel360.co.za/v1.1/org/<ORG_ID>/whatsapp/attachments",
        headers={"Authorization": "Bearer <API_KEY>"},
        files={"source": ("september-invoice.pdf", file, "application/pdf")},
    )

print(response.json())
```

{% endtab %}

{% tab title="Postman" %}

1. Set the method to `POST` and enter the URL above.
2. Under **Authorization**, choose **Bearer Token** and enter your API key.
3. Under **Body**, choose **form-data**.
4. Enter `source` in the **Key** column, change the row's type from **Text** to **File**, and select your file as the **Value**.
5. On the **Headers** tab, make sure you have not added a `Content-Type` header of your own.
   {% endtab %}
   {% endtabs %}

## Response

The API returns `201` with the hosted file:

```json
{
  "attachment": {
    "mediaUrl": "https://media.smooch.io/apps/<APP_ID>/<FILE_ID>/september-invoice.pdf",
    "mediaType": "application/pdf",
    "mediaSize": 48213
  }
}
```

| Field       | Meaning                                 |
| ----------- | --------------------------------------- |
| `mediaUrl`  | The public link to the file.            |
| `mediaType` | The file's type, as detected on upload. |
| `mediaSize` | The file's size in bytes.               |

Anyone with the `mediaUrl` can open the file. Treat the link with the same care as the file itself.

## Send it in a reply

Pass `attachment.mediaUrl` as `mediaUrl` in a [media reply](https://docs.channel360.co.za/api-usage/reply-to-a-customer/send-a-media-reply.md):

```json
{
  "type": "document",
  "mediaUrl": "https://media.smooch.io/apps/<APP_ID>/<FILE_ID>/september-invoice.pdf",
  "filename": "September Invoice.pdf",
  "text": "Your invoice for September"
}
```

Upload the file shortly before you send it, and do not keep the link as your record of the file. Your own systems should stay the source of truth.

## What can go wrong

| What you see                                     | Why                                                                          | What to do                                                                                   |
| ------------------------------------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **400** `Unexpected field`                       | The file was sent in a field not named `source`, or in a field with no name. | Name the form field `source`.                                                                |
| **400** `No file supplied on the 'source' field` | The form contained no file.                                                  | Attach the file to the `source` field. In Postman, set the row's type to **File**.           |
| **400** `File too large`                         | The file is larger than 20 MB.                                               | Host the file yourself and pass its link as `mediaUrl`.                                      |
| **400** `Smooch integration not set up`          | The upload service is not available for your organisation.                   | Host the file yourself and pass its link as `mediaUrl`.                                      |
| **400** with any other message                   | The upload could not be completed.                                           | Try again. If it keeps failing, host the file yourself or contact Channel360 support.        |
| **401 / 403**                                    | Wrong API key or organisation.                                               | See [Authentication](https://docs.channel360.co.za/api-usage/get-started/authentication.md). |

## Next

{% content-ref url="/pages/jz4KOq3pj3oHSszPwn3O" %}
[Send a media reply](https://docs.channel360.co.za/api-usage/reply-to-a-customer/send-a-media-reply.md)
{% endcontent-ref %}
