Отдаёт подписанную ссылку на файл сообщения. В уведомлениях и истории ссылка уже есть (downloadUrl) — downloadFile нужен, когда у вас только chatId и idMessage: например, для старого сообщения, которое вы не сохранили.
| Запрос | POST /waInstance{idInstance}/downloadFile/{apiTokenInstance} |
| Тело | JSON |
| Каналы | MAX, Telegram, WhatsApp, почта |
Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
chatId |
string | да | чат сообщения — id в этом канале |
idMessage |
string | да | id сообщения с файлом |
Пример запроса
Ссылка на фото, которое прислала Мария:
curl
curl -X POST "$GRATIO_URL/waInstance$GRATIO_ID/downloadFile/$GRATIO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"chatId": "8695836", "idMessage": "117428960974949548"}'
Python
import os
import requests
BASE = f"{os.environ['GRATIO_URL']}/waInstance{os.environ['GRATIO_ID']}"
TOKEN = os.environ["GRATIO_TOKEN"]
url = f"{BASE}/downloadFile/{TOKEN}"
payload = {"chatId": "8695836", "idMessage": "117428960974949548"}
response = requests.post(url, json=payload, timeout=60)
print(response.status_code, response.json())
Node.js
const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/waInstance${GRATIO_ID}`;
const url = `${base}/downloadFile/${GRATIO_TOKEN}`;
const payload = { chatId: "8695836", idMessage: "117428960974949548" };
const response = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
});
console.log(response.status, await response.json());
PHP
<?php
$base = getenv('GRATIO_URL') . '/waInstance' . getenv('GRATIO_ID');
$url = $base . '/downloadFile/' . getenv('GRATIO_TOKEN');
$payload = ['chatId' => '8695836', 'idMessage' => '117428960974949548'];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);
Пример ответа
Ответ 200 OK:
{"downloadUrl": "https://api.gratio.net/media/7100000001/8695836/117428960974949548/0/d8f9…"}
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
downloadUrl |
string | ссылка на первый файл сообщения. Токен для скачивания не нужен, ссылка не истекает |
Скачивание по ссылке
Ссылка открывается обычным GET — например, curl:
curl -o photo.jpg "https://api.gratio.net/media/7100000001/8695836/117428960974949548/0/d8f9…"
downloadFile отвечает сразу и не проверяет, есть ли в сообщении файл. Gratio начинает забирать файл у мессенджера в фоне; если к первому запросу по ссылке файл ещё не у Gratio, он скачается в этот момент.
| Ответ по ссылке | Когда |
|---|---|
200 и сам файл |
с его Content-Type и именем в Content-Disposition |
404 с code |
нет такого сообщения (not_found), в нём нет файла (no_file), мессенджер не отдал файл (media_unavailable), файл больше 100 МБ (file_too_large) |
404 без code |
ссылка с неверной подписью |
503 |
канал сейчас не на связи, а файла у Gratio ещё нет — повторите позже |
Ошибки
| Код | code |
Когда | Что делать |
|---|---|---|---|
400 |
validation |
нет chatId или idMessage |
добавить поле |
Ошибки самого файла приходят при скачивании по ссылке — таблица выше. Общие правила — в статье Ответы и ошибки.
Особенности каналов
- Альбом. Ссылка ведёт на первый файл. Ссылки на остальные — в уведомлении о сообщении, в
additionalFiles, см. Файлы и альбомы. - Почта. Ссылка ведёт на первое вложение письма. Все вложения и письмо целиком — getEmail.
- Telegram. Файлы публичного канала можно скачать без вступления — после getChatPreview.
Что дальше
- Файлы и ссылки на них — как устроены ссылки и хранилище.
- Элемент журнала —
downloadUrlв истории. - Файлы и альбомы — файлы во входящих уведомлениях.