# Media

> Upload and download media. WhaBuzz proxies Meta and stores nothing.

Canonical: https://docs.whabuzz.com/api/media/

Upload and download media. WhaBuzz proxies Meta and stores nothing.

Base URL `https://api.whabuzz.com`. Every request needs `Authorization: Bearer <key>` unless the operation says otherwise; see [Authentication](https://docs.whabuzz.com/authentication.md). Errors follow the [two-source contract](https://docs.whabuzz.com/errors.md).

Operations on this page:

- [`POST /v1/media`](#uploadMedia): Upload media to Meta for sending
- [`GET /v1/media/{media_id}`](#downloadMedia): Download inbound media
- [`DELETE /v1/media/{media_id}`](#deleteMedia): Delete uploaded media from Meta

## Upload media to Meta for sending {#uploadMedia}

`POST /v1/media`

Stored by Meta, not by WhaBuzz.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `uploadMedia`.

**Request body** (`multipart/form-data`, required)

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | string (binary) | yes |  |
| `type` | string | yes |  |
| `from` | string | yes |  |

cURL:

```bash
curl -X POST "https://api.whabuzz.com/v1/media" \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -F file=@./photo.jpg \
  -F type=<type> \
  -F from=<from>
```

**Responses**

**200** Meta's response verbatim

```json
{
  "id": "1479537139650973"
}
```

**Common errors.** Shape and meanings are on the [Errors page](https://docs.whabuzz.com/errors.md).

| HTTP | WhaBuzz code | Meaning |
|---|---|---|
| 400 | `131030` | Meta's error, passed through with Meta's HTTP status |

## Download inbound media {#downloadMedia}

`GET /v1/media/{media_id}`

Streams the bytes from Meta. WhaBuzz never stores media. Meta keeps inbound media for a limited time; download promptly.

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `downloadMedia`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `media_id` | path | string | yes |  |
| `from` | query | string | no | Number that received it; needed only when the tenant has several WABAs. |

cURL:

```bash
curl -X GET "https://api.whabuzz.com/v1/media/$MEDIA_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** The file

Body: `application/octet-stream`.

**404** Meta does not know this media id (passed through)

```json
{
  "source": "meta",
  "error": {
    "message": "Unsupported get request. Object with ID '1479537139650973' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
    "type": "GraphMethodException",
    "code": 100,
    "error_subcode": 33,
    "fbtrace_id": "AxYz0123456789"
  }
}
```

## Delete uploaded media from Meta {#deleteMedia}

`DELETE /v1/media/{media_id}`

**Auth:** API key (tenant key, or app key with `X-WhaBuzz-Tenant`). **Operation id:** `deleteMedia`.

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `media_id` | path | string | yes |  |
| `from` | query | string | no |  |

cURL:

```bash
curl -X DELETE "https://api.whabuzz.com/v1/media/$MEDIA_ID" \
  -H "Authorization: Bearer $WHABUZZ_KEY"
```

**Responses**

**200** Meta's response verbatim

```json
{
  "success": true
}
```