SendFileByUpload#
Для метода SendFileByUpload рекомендуется использовать хост media.green-api.com
Метод предназначен для отправки файла, загружаемого через форму (form-data). Сообщение будет добавлено в очередь на отправку, в ответе Вы получите ссылку на загруженный файл. Скорость отправки сообщений из очереди регулирует параметр Интервал отправки сообщений.
Файлы видео, аудио и изображений отправляются, как и в родном MAX с возможностью просмотра и прослушки. Документы отправляются так же, как в родном MAX. Тип отправляемого файла и способ его отправки определяется по расширению файла. Описание добавляется только к изображениям и видео.
Файлы
Максимальный размер отправляемых файлов равен 100 Мбайт.
Отправка нескольких файлов одним запросом невозможна. 1 файл отправляется только 1 сообщением.
Ограничений на разрешения изображений нет. Однако при отправке изображений через API с разрешением свыше 3000х3000 пикселей, превью не формируется.
Срок действия ссылки 15 дней.
Ссылку можно использовать повторно методом SendFileByUrl.
Для метода используются ограничения на частоту запросов в секунду.
Запрос#
Для отправки файла требуется выполнить запрос по адресу:
{{mediaUrl}}/v3/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}
Для получения параметров запроса mediaUrl
, idInstance
и apiTokenInstance
обратитесь к разделу Перед началом работы.
Параметры запроса#
Параметр | Тип | Обязательный | Описание |
---|---|---|---|
chatId | string | Да | Идентификатор чата |
file | file | Да | Отправляемый файл |
fileName | string | Нет | Название файла. Должно содержать расширение файла. Требуется использовать кодировку UTF-8 без BOM. Например: test.jpg |
caption | string | Нет | Описание под файлом. Описание добавляется к видео, изображениям, документам, файлам. Принимает значение до 4000 символов включительно. если написать больше 4000, то сообщение не отправится. |
Время на отправку файла
Отправка файлов происходит в несколько этапов:
- Получение файла
- Выгрузка файла на сервер MAX
- Запрос на отправку файла в MAX
Время на отправку файла зависит от размера файла, скорости получения файла и обработки файла MAX. В зависимости от данных факторов время на отправку файла может меняться от 1 до 20 секунд.
Ответ#
Поля ответа#
Поле | Тип | Описание |
---|---|---|
idMessage | string | Идентификатор отправленного сообщения |
urlFile | string | Ссылка на файл (срок действия ссылки 15 дней) |
Пример тела ответа#
Успешное выполнение метода#
{
"idMessage": "2712345112345"
}
Выполнение метода с ошибкой#
{
"statusCode": 400,
"timestamp": "2025-08-15T07:04:56.987Z",
"path": "/waInstance3100000001/sendFileByUpload/9ece01c05bbe44768fb674840138bbe6af876fe49b69418fbf",
"message": "Validation failed. Details: 'chatId' is not allowed to be empty"
}
Ошибки SendFileByUpload#
Перечень общих для всех методов ошибок смотрите в разделе Стандартные ошибки
Код HTTP | Идентификатор ошибки | Описание |
---|---|---|
200 | failed to upload file | Превышение 100кб в теле запроса |
400 | failed to upload file | Отсутствует поле chatId / Присутствует лишнее поле / Указан некорректный messageId Отсутствует файл / Неверный тип поля / Используются не form-data / Некорректный номер |
400 | Bad Request Validation failed | Ошибка валидации |
400 | file should not be empty | Пользователь отправил пустой файл. Загружаемый файл не должен быть пустым. |
413 | request entity too large | Превышение допустимого размера файла (~99.9mb) Возникает при отправке файлов в обработке 1С (версия 8.3.22.1923). Возможное решение: Сменить версию 1С |
500 | Internal Server Error failed to upload file | Отсутствует поле file |
500 | Internal Server Error | Указан неверный метод для запроса. Укажите метод POST и повторите отправку |
Пример тела запроса#
Примеры кода
import requests
url = "{{mediaUrl}}/v3/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}"
payload = {'chatId': '10000000',
'caption': 'Описание'}
files = [
('file', ('window.jpg', open('C:/window.jpg','rb'),'image/jpeg'))
]
headers= {}
response = requests.post(url, data=payload, files=files)
print(response.text.encode('utf8'))
curl --location '{{mediaUrl}}/v3/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}' \
--form 'chatId="10000000"' \
--form 'file=@"/Users/you/files/file.jpeg"' \
--form 'fileName="file.jpg"'
var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
.append({{mediaUrl}})
.append("/v3/waInstance").append({{idInstance}})
.append("/sendFileByUpload/")
.append({{apiTokenInstance}});
var headers = new HttpHeaders();
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
var form = new LinkedMultiValueMap<>();
form.add("chatId", "10000000");
form.add("file", new FileSystemResource(new File("/Users/you/files/file.jpeg")));
form.add("fileName", file.jpg);
form.add("caption", "Описание");
var requestEntity = new HttpEntity<>(form, headers);
var response = restTemplate.exchange(requestUrl.toString(), HttpMethod.POST, requestEntity, String.class);
System.out.println(response);
var file = new File("/Users/user/Desktop/fileExample.jpeg");
var requestUrl = new StringBuilder();
requestUrl
.append({{mediaUrl}})
.append("/v3/waInstance").append({{idInstance}})
.append("/sendFileByUpload/")
.append({{apiTokenInstance}});
var form = new HashMap<String, Object>();
form.put("chatId", dto.getChatId());
form.put("file", dto.getFile());
form.put("fileName", dto.getFileName());
form.put("caption", dto.getCaption());
var response = Unirest.post(requestUrl.toString())
.fields(form)
.asString();
System.out.println(response);