Медиафайлы
/v1/media
С помощью узла media можно загружать, получать и удалять медиафайлы.
Границы контекста
С этим узлом связаны следующие границы контекста:
| Граница контекста | Описание |
|---|---|
С помощью этой границы контекста можно получать и удалять медиафайлы. |
Прежде чем начать
После отправки сообщения с медиафайлом этот медиафайл хранится на серверах WhatsApp в течение 14 дней. Если пользователь отправляет запрос на скачивание медиафайла по истечении этого срока, серверы WhatsApp запрашивают этот файл у локального клиента WhatsApp Business API. Если медиафайл уже удален, пользователь получит сообщение о том, что он недоступен.
Делать предположение о том, что медиафайл был скачан, только на основании отчетов о доставке и прочтении небезопасно. Как правило, исходящие медиафайлы можно удалять по истечении 30 дней, однако так или иначе рекомендуем применять стратегию, отвечающую особенностям работы вашей компании.
Ограничения
- Если для загрузки медиафайла вы используете не ссылку на его URL, а процедуру загрузки, то его необходимо загрузить в том медиафайлов. Когда загрузка будет завершена, вы сможете отправить сообщение, используя ID медиафайла.
- Приложение обрабатывает загруженный медиафайл перед его отправкой на сервер. Максимальный размер медиафайла, который можно загрузить на узел
media, составляет 100 МБ, однако имеются определенные ограничения на постобработку различных типов файлов, перечисленные в таблице Размер медиафайлов при постобработке ниже. - За хранение медиафайлов отвечает компания. Если том медиафайлов переполняется, при отправке сообщений возникают ошибки.
- Не поддерживается:
- отправка медиафайлов в виде байтовых потоков;
- отправка сообщений с анимированными стикерами.
Загрузка
Чтобы загрузить медиафайл, отправьте запрос POST к /v1/media. Тело локального запроса должно содержать двоичные данные медиафайла, а для заголовка Content-Type необходимо установить тип загружаемого медиафайла. Возможные варианты см. в разделе Поддерживаемые типы контента.
Для загрузки двоичных данных обычно используется запрос POST HTTP. Например, для загрузки изображения нужно отправить запрос POST с байтами изображения в полезных данных. Также можно использовать cURL с параметром --data-binary для считывания и использования неизмененного двоичного файла.
Пример
Загрузка медиафайла:
POST /v1/media Content-Type: image/jpeg or other appropriate media type
your-binary-media-data
Загрузка медиафайла с помощью cURL:
curl -X POST \ https://your-webapp-hostname:your-webapp-port/v1/media \ -H 'Authorization: Bearer your-auth-token' \ -H 'Content-Type: image/jpeg' \ # or other appropriate media type --data-binary @your-file-path
В обоих случаях при успехе в ответе возвращается поле id, которое необходимо для получения медиафайла или отправки сообщения с медиафайлом клиентам.
{
"media": [
{
"id": "f043afd0-f0ae-4b9c-ab3d-696fb4c8cd68"
}
]
}
Если в ответе содержится сообщение об ошибке, обратитесь к разделу Сообщения об ошибках и коды статусов.
Поддерживаемые типы контента
| Медиафайлы | Поддерживаемые типы контента |
|---|---|
|
Примечание. Для клиентов WA поддерживаются только одноканальные аудиофайлы ogg/opus. |
| Любой действительный тип MIME. |
|
На текущий момент мы не поддерживает изображения с прозрачным фоном. |
|
|
|
Примечания:
|
Размеры медиафайлов при постобработке
Это максимальный допустимый размер медиафайла после сжатия и шифрования.
| Тип медиафайла | Размер |
|---|---|
| 16 МБ |
| 100 МБ |
| 5 МБ |
| 100 КБ |
| 16 МБ |
Часто задаваемые вопросы
К изображениям подписи можно добавлять в качестве описания. Текст подписи отображается для изображений полностью как на устройствах Android, так и на iPhone.
Для документов подпись заменяет собой имя файла. Она отображается на устройстве пользователя не как описание, а как имя файла. На iPhone текст отображается целиком, в то время как на устройствах Android имя файла обрезается (таковы особенности текущей реализации WhatsApp на обеих платформах).
Вы сами принимаете решение об удалении медиафайлов.
После загрузки медиафайла вы получаете его ID, который затем можно использовать для отправки сообщения с загруженным мультимедийным содержимым получателю. При отправке сообщения с медиафайлом WhatsApp Business API зашифровывает и загружает этот файл на серверы WhatsApp, где он хранится в течение 14 дней. После этого вы можете удалить медиафайл по его ID либо сохранить для использования в будущем. Мы рекомендуем хранить медиафайлы в течение 30 дней, однако вы самостоятельно определяете политику хранения с учетом потребностей вашей организации.
Механизм очистки для исходящих или входящих медиафайлов не предусмотрен. Вы можете удалять свои медиафайлы вручную, находя их в своей файловой системе.
Чтобы определить точку подключения тома медиафайлов, можно воспользоваться командой docker.
Запрос
docker volume inspect whatsappMedia
Ответ
[
{
"Driver": "local",
"Labels": {},
"Mountpoint": "/var/lib/docker/volumes/whatsappMedia/_data",
"Name": "whatsappMedia",
"Options": {},
"Scope": "local"
}
]Затем запустите команду ls с полученным путем файла Mountpoint, чтобы увидеть все входящие медиафайлы:
ls /var/lib/docker/volumes/whatsappMedia/_data/
В конфигурации AWS том медиафайлов подключается по пути /mnt/wa/media на хосте.
Для этого нужно отправить через WhatsApp Business API не менее 4 изображений подряд. Если в момент получения изображений у пользователя включено свое представление чата, то представление альбома не будет доступно до следующего сеанса.
Альбом не создается, если выполняется хотя бы одно из следующих условий:
- Изображения снабжены подписями.
- Разделитель не удается прочитать, и пользователь видит только некоторые изображения.
- Дата доставки в заголовке одного из изображений отличается от дат других.
Нет, в настоящее время для совместного доступа Coreapp и Webapp к тому медиафайлов необходимо использовать AWS EFS.
Максимальный размер загружаемого файла составляет 64 МБ, и это ограничение распространяется на любое изображение, документ или видео, которые вы отправляете в сообщении.