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

SendFileByUrl#

Test Postman Apidog

Метод предназначен для отправки файла, загружаемого по ссылке. Сообщение будет добавлено в очередь на отправку. Сообщение на отправку хранится 24 часа в очереди и будет отправлено сразу же после авторизации телефона. Скорость отправки сообщений из очереди регулирует параметр Интервал отправки сообщений.

Для формирования ссылки на файл, вы можете воспользоваться сервисами внешнего хранения файлов.
Мы рекомендуем использовать наше внешнее хранилище файлов с помощью метода UploadFile.

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

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

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

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

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

Запрос#

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

POST
{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}

Для получения параметров запроса apiUrl, idInstance и apiTokenInstance обратитесь к разделу Перед началом работы.

Параметры запроса#

Параметр Тип Обязательный Описание
chatId string Да Идентификатор чата
urlFile string Да Ссылка на отправляемый файл
fileName string Да Название файла. Должно содержать расширение файла. Требуется использовать кодировку UTF-8 без BOM. Например: test.jpg
caption string Нет Описание под файлом. Описание добавляется к видео, изображениям. Максимальная длина поля 20000 символов.
quotedMessageId string Нет Идентификатор цитируемого сообщения. При заполнении параметра сообщение отправится с цитированием указанного сообщения чата.
Цитирование сообщения возможно только из того же чата, в который производится отправка.
Для отправки сообщений из другого чата используется метод ForwardMessages

Примечание

  • Рекомендации по формату ссылок

    1. В ссылке могут быть использованы символы a-z, A-Z, 0-9, - (дефис), _ (нижнее подчеркивание)
    2. В ссылке должны отсутствовать спец символы ~$€%#£?! и пробелы
    3. Кодировка символов ссылки UTF-8 без BOM
    4. Требуется передавать не кодированные ссылки (система сама кодирует ссылку)
    5. Требуется чтобы ссылка указывала на конкретный файл, а не на html страницу примеры ссылок
    6. Требуется использовать быстрое хранилище, без ограничения на количество запросов файлов
  • Поле fileName

    Требуется обязательно указывать поле fileName с верным расширением файла.

    Определение типа файла системой:

    1. По расширению указанного в названии файла, в поле fileName
    2. Если поле fileName не содержит расширения, то тип файла получаем по Content-Type из заголовка ссылки
    3. Если в заголовке поле Content-Type отсутствует или содержит несуществующий тип файла, система постарается определить тип файла по байтам файла
    4. Если система не сможет определить тип файла, то произойдет отправка с типом по умолчанию (бинарный файл)

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

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

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

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

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

Для корректной работы с механизмом цитирования сообщений система должна знать о сообщении, которое будет процитировано. Убедится о том что сообщение доступно к цитированию можно запросив метод журналирования getMessage, если сообщение отсутствует в системе, то цитировать такое сообщение невозможно.

  • Для цитирования входящих сообщений необходимо включить настройку Получать уведомления о входящих сообщениях и файлах.

  • Для цитирования исходящих сообщений отправленных с телефона, включите настройку Получать уведомления о сообщениях, отправленных с телефона.
    Так сообщения будут попадать в систему и их можно будет цитировать.

Установку настроек можно сделать методом SetSettings или через личный кабинет.

Пример тела запроса#

Отправка сообщения в личный чат:

{
    "chatId": "11001234567@c.us",
    "urlFile": "https://my.site.com/img/horse.png",
    "fileName": "horse.png",
    "caption": "Лошадка"
}

Отправка сообщения в групповой чат:

{
    "chatId": "120363043968066561@g.us",
    "urlFile": "https://my.site.com/img/horse.png",
    "fileName": "horse.png",
    "caption": "Лошадка"
}

Отправка сообщения с цитированием:

{
    "chatId": "11001234567@с.us",
    "urlFile": "https://my.site.com/img/horse.png",
    "fileName": "horse.png",
    "caption": "Лошадка",
    "quotedMessageId": "361B0E63F2FDF95903B6A9C9A102F34B"
}

Ответ#

Поля ответа#

Поле Тип Описание
idMessage string Идентификатор отправленного сообщения

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

{
    "idMessage": "3EB0C767D097B7C7C030"
}

Ошибки SendFileByUrl#

Перечень общих для всех методов ошибок смотрите в разделе Стандартные ошибки

Код HTTP Идентификатор ошибки Описание
400 Bad Request
Validation failed
Ошибка валидации
400 Validation failed.
Details: url has incorrect format. It should start with http(s)://'
Некорректная ссылка
500 request entity too large Превышение допустимой длины Json (>100кб)

Отправка с неверным идентификатором цитируемого сообщения

В случае некорректного указания quotedMessageId, система вернёт код 200 и id отправляемого сообщения, но оно не будет доставлено получателю.

Примеры кода#

import requests

url = "{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}"

payload = {
"chatId": "11001234567@c.us", 
"urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375", 
"fileName": "horse.png", 
"caption": "лошадка"
}
headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, json=payload)

print(response.text.encode('utf8'))
curl --location '{{apiUrl}}/waInstance{{idInstance}}/sendFileByUrl/{{apiTokenInstance}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chatId": "12345678910@c.us",
    "urlFile": "https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375",
    "fileName": "horse.png",
    "caption": "лошадка"
}'
var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/sendFileByUrl/")
    .append({{apiTokenInstance}});

var headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);

var jsonBody = "{\r\n   \t\"chatId\": \"11001234567@c.us\",\r\n\t\"urlFile\": \"https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375\",\r\n\t\"fileName\": \"horse.png\",\r\n\t\"caption\": \"little horse\"\r\n}";

var requestEntity = new HttpEntity<>(jsonBody, headers);

var response = restTemplate.exchange(requestUrl.toString(), HttpMethod.POST, requestEntity, String.class);
System.out.println(response);
var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/sendFileByUrl/")
    .append({{apiTokenInstance}});

var response = Unirest.post(requestUrl.toString())
    .header("Content-Type", "application/json")
    .body("{\r\n   \t\"chatId\": \"11001234567@c.us\",\r\n\t\"urlFile\": \"https://avatars.mds.yandex.net/get-pdb/477388/77f64197-87d2-42cf-9305-14f49c65f1da/s375\",\r\n\t\"fileName\": \"horse.png\",\r\n\t\"caption\": \"little horse\"\r\n}")
    .asString();

System.out.println(response);
Sub SendFileByUrl()
    Dim url As String
    Dim RequestBody As String
    Dim http As Object
    Dim response As String

    ' The apiUrl, idInstance and apiTokenInstance values are available in console, double brackets must be removed
    url = "{{apiUrl}}/waInstance{{idInstance}}/SendFileByUrl/{{apiTokenInstance}}"

    ' chatId is the number to send the message (@c.us for private chats, @g.us for group chats), urlFile - url link, fileName - file name with extension, caption - title
    RequestBody = "{""chatId"":""71234567890@c.us"",""urlFile"":""https://my.site.com/img/horse.png"",""fileName"":""horse.png"",""caption"":""Лошадка""}"

    Set http = CreateObject("MSXML2.XMLHTTP")

    With http
        .Open "POST", url, False
        .setRequestHeader "Content-Type", "application/json"
        .Send RequestBody
    End With

    response = http.responseText

    Debug.Print response

    ' Outputting the answer to the desired cell
    ' Range("A1").Value = response

    Set http = Nothing
End Sub