SendFileByUpload#
Для метода SendFileByUpload рекомендуется использовать хост media.green-api.com
Метод предназначен для отправки файла, загружаемого через форму (form-data). Сообщение будет добавлено в очередь на отправку, в ответе Вы получите ссылку на загруженный файл. Скорость отправки сообщений из очереди регулирует параметр Интервал отправки сообщений.
Файлы видео, аудио и изображений отправляются, как и в родном WhatsApp с возможностью просмотра и прослушки. Документы отправляются так же как в родном WhatsApp. Тип отправляемого файла и способ его отправки определяется по расширению файла. Описание добавляется только к изображениям и видео.
Файлы
Максимальный размер отправляемых файлов равен 100 Мбайт.
Отправка нескольких файлов одним запросом невозможна. 1 файл отправляется только 1 сообщением. Возможность отправки нескольких файлов одновременно формируется только на стороне приложения WhatsApp.
Ограничений на разрешения изображений нет. Однако при отправке изображений через API с разрешением свыше 3000х3000 пикселей, превью не формируется.
Список файловых форматов, которые успешно отправляются и принимаются через API
Срок действия ссылки 15 дней.
Ссылку можно использовать повторно методом SendFileByUrl.
Запрос#
Для отправки файла требуется выполнить запрос по адресу:
{{mediaUrl}}/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}
Для получения параметров запроса mediaUrl
, idInstance
и apiTokenInstance
обратитесь к разделу Перед началом работы.
Параметры запроса#
Параметр | Тип | Обязательный | Описание |
---|---|---|---|
chatId | string | Да | Идентификатор чата |
file | file | Да | Отправляемый файл |
fileName | string | Нет | Название файла. Должно содержать расширение файла. Требуется использовать кодировку UTF-8 без BOM. Например: test.jpg |
caption | string | Нет | Описание под файлом. Описание добавляется к видео, изображениям, документам, файлам. Максимальная длина поля 20000 символов. |
quotedMessageId | string | Нет | Идентификатор цитируемого сообщения. При заполнении параметра сообщение отправится с цитированием указанного сообщения чата. Цитирование сообщения возможно только из того же чата, в который производится отправка. Для отправки сообщений из другого чата используется метод ForwardMessages |
Время на отправку файла
Отправка файлов происходит в несколько этапов:
- Получение файла
- Выгрузка файла на сервер WhatsApp
- Запрос на отправку файла в WhatsApp
Время на отправку файла зависит от размера файла, скорости получения файла и обработки файла WhatsApp. В зависимости от данных факторов время на отправку файла может меняться от 1 до 20 секунд.
Цитирование сообщений
Для корректной работы с механизмом цитирования сообщений система должна знать о сообщении, которое будет процитировано. Убедится о том что сообщение доступно к цитированию можно запросив метод журналирования getMessage, если сообщение отсутствует в системе, то цитировать такое сообщение невозможно.
-
Для цитирования входящих сообщений необходимо включить настройку
Получать уведомления о входящих сообщениях и файлах
. -
Для цитирования исходящих сообщений отправленных с телефона, включите настройку
Получать уведомления о сообщениях, отправленных с телефона
.
Так сообщения будут попадать в систему и их можно будет цитировать.
Установку настроек можно сделать методом SetSettings или через личный кабинет.
Ответ#
Поля ответа#
Поле | Тип | Описание |
---|---|---|
idMessage | string | Идентификатор отправленного сообщения |
urlFile | string | Ссылка на файл (срок действия ссылки 15 дней) |
"Как получить информацию о сроке хранения файла в хранилище GREEN-API?"
Пример тела ответа#
{
"idMessage": "3EB0C767D097B7C7C030",
"urlFile": "https://sw-media-out.storage.yandexcloud.net/1101776123/c1aabd48-c1c2-49b1-8f2d-f575a41777be.jpg"
}
Ошибки 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 и повторите отправку |
Отправка с неверным идентификатором цитируемого сообщения
В случае некорректного указания quotedMessageId
, система вернёт код 200 и id отправляемого сообщения, но оно не будет доставлено получателю.
Пример тела запроса#
Примеры кода
import requests
url = "{{mediaUrl}}/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}"
payload = {'chatId': '79876543210@c.us',
'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}}/waInstance{{idInstance}}/sendFileByUpload/{{apiTokenInstance}}' \
--form 'chatId="12345678910@c.us"' \
--form 'file=@"/Users/you/files/file.jpeg"' \
--form 'fileName="file.jpg"'
var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
.append({{mediaUrl}})
.append("/waInstance").append({{idInstance}})
.append("/sendFileByUpload/")
.append({{apiTokenInstance}});
var headers = new HttpHeaders();
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
var form = new LinkedMultiValueMap<>();
form.add("chatId", "12345678910@c.us");
form.add("file", new FileSystemResource(new File("/Users/you/files/file.jpeg")));
form.add("fileName", file.jpg);
form.add("caption", "Описание");
form.add("quotedMessageId", "BAE5F4886F6F2D05");
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("/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());
form.put("quotedMessageId", dto.getQuotedMessageId());
var response = Unirest.post(requestUrl.toString())
.fields(form)
.asString();
System.out.println(response);
program sendFileByUpload;
{$APPTYPE CONSOLE}
uses
System.SysUtils,
System.Classes, System.Net.HttpClient, System.Net.Mime, System.Net.URLClient, System.Net.HttpClientComponent;
var
HttpClient: TNetHTTPClient;
Response: IHTTPResponse;
FormData: TMultipartFormData;
EndpointURL, MEDIA_URL, ID_INSTANCE, API_TOKEN_INSTANCE: string;
begin
MEDIA_URL := 'https://media.green-api.com';
ID_INSTANCE := '110100001';
API_TOKEN_INSTANCE := 'd75b3a66374942c5b3c019c698abc2067e151558acbd451234';
EndpointURL := MEDIA_URL +'/waInstance' + ID_INSTANCE + '/sendFileByUpload/' + API_TOKEN_INSTANCE;
HttpClient := TNetHTTPClient.Create(nil);
FormData := TMultipartFormData.Create();
FormData.AddField('chatId', '71234567890@c.us');
FormData.AddField('caption', 'test');
FormData.AddFile('file', 'C:\tmp\bp.png');
try
Response := HTTPClient.Post(EndpointURL, FormData, nil);
if Response.StatusCode = 200 then
Writeln('[Response]: ' + Response.ContentAsString)
else
Writeln('[ERROR ' + IntToStr(Response.StatusCode) + ']:' + Response.StatusText + '' + Response.ContentAsString);
readln;
except
on E: Exception do
Writeln(E.ClassName, ': ', E.Message);
end;
HttpClient.Free;
FormData.Free;
end.