Перейти к содержанию

SendFileByUpload#

Test Postman

Для метода SendFileByUpload рекомендуется использовать хост media.green-api.com

Метод предназначен для отправки файла, загружаемого через форму (form-data). Сообщение будет добавлено в очередь на отправку, в ответе Вы получите ссылку на загруженный файл. Скорость отправки сообщений из очереди регулирует параметр Интервал отправки сообщений.

Срок действия ссылки 15 дней.

Ссылку можно использовать повторно методом SendFileByUrl.

Файлы видео, аудио и изображений отправляются, как и в родном WhatsApp с возможностью просмотра и прослушки. Документы отправляются так же как в родном WhatsApp. Тип отправляемого файла и способ его отправки определяется по расширению файла. Описание добавляется только к изображениям и видео.

Максимальный размер отправляемых файлов равен 100 Мбайт.

Отправка нескольких файлов одним запросом невозможна. 1 файл отправляется только 1 сообщением. Возможность отправки нескольких файлов одновременно формируется только на стороне приложения WhatsApp.

Ограничений на разрешения изображений нет. Однако при отправке изображений через API с разрешением свыше 3000х3000 пикселей, превью не формируется.

Список файловых форматов, которые успешно отправляются и принимаются через API

Запрос#

Для отправки файла требуется выполнить запрос по адресу:

POST
{{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

Время на отправку файла

Отправка файлов происходит в несколько этапов:

  1. Получение файла
  2. Выгрузка файла на сервер WhatsApp
  3. Запрос на отправку файла в WhatsApp

Время на отправку файла зависит от размера файла, скорости получения файла и обработки файла WhatsApp. В зависимости от данных факторов время на отправку файла может меняться от 1 до 20 секунд.

Цитирование сообщений

Чтобы процитировать входящие сообщения, включите настройку Получать уведомления о входящих сообщениях и файлах.
Чтобы процитировать исходящие сообщения, включите настройки Получать уведомления о сообщениях, отправленных с телефона и Получать уведомления о сообщениях, отправленных с API методом SetSettings или через личный кабинет.

Ответ#

Поля ответа#

Поле Тип Описание
idMessage string Идентификатор отправленного сообщения
urlFile string Ссылка на файл (срок действия ссылки 15 дней)

Пример тела ответа#

{
    "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': '11001234567@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.