> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /project/{project_id}/get-media — Fetch Media by ID

> Download a media file from WhatsApp by its media ID, supporting arraybuffer, JSON, text, and stream response formats for flexible use.

Use this endpoint to download media files received via WhatsApp messages. When a contact sends your business an image, audio clip, video, or document, WhatsApp stores the file and provides a `media_id` in the incoming message payload. Pass that ID to this endpoint to retrieve the actual file content.

## Endpoint

```text theme={null}
POST https://connect.api-wa.co/project-apis/v1/project/{project_id}/get-media
```

## Authentication

```text theme={null}
X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD
```

## Path Parameters

<ParamField path="project_id" type="string" required>
  Your Convo project ID.
</ParamField>

## Request Body

<ParamField body="id" type="string" required>
  The media ID of the file you want to retrieve. This value is found in incoming message webhook payloads (e.g., `message.image.id`, `message.audio.id`, `message.document.id`) or in the response from the Get Message Details endpoint.
</ParamField>

<ParamField body="responseType" type="string">
  The format in which the media content is returned. Accepted values:

  * `"arraybuffer"` *(default)* — Returns the raw binary data as an array buffer. Suitable for saving files to disk or processing binary content in server-side code.
  * `"json"` — Returns a JSON object containing a signed download URL or media metadata.
  * `"text"` — Returns the media content as a plain text string.
  * `"stream"` — Returns the media as a readable stream. Suitable for piping data to a file or HTTP response.
</ParamField>

## Request Example

```bash theme={null}
curl -X POST \
  "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/get-media" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1745702309699251",
    "responseType": "arraybuffer"
  }'
```

## Response

The response format depends on the `responseType` you specify:

| `responseType` | Response                                               |
| -------------- | ------------------------------------------------------ |
| `arraybuffer`  | Raw binary data of the media file                      |
| `json`         | `{"status": true}` with media metadata or a signed URL |
| `text`         | Media content as a plain text string                   |
| `stream`       | A readable binary stream of the media file             |

For `json` mode:

```json theme={null}
{
  "status": true
}
```

<ResponseField name="status" type="boolean">
  Returns `true` when the media was successfully retrieved in JSON mode.
</ResponseField>

<Note>
  Media IDs are obtained from incoming message payloads delivered via webhooks. When a contact sends a media message (image, audio, video, or document), the webhook payload includes a field such as `message.image.id` or `message.document.id`. **Note that media IDs expire after a short period** — download the media promptly after receiving the ID.
</Note>

## Error Responses

| Status Code | Description                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `400`       | Bad Request — The `id` field is missing or the `responseType` value is not valid.                                           |
| `500`       | Internal Server Error — An unexpected server-side error occurred, or the media ID has expired. Retry with a fresh media ID. |