Медиа в WhatsApp API: типы файлов и ограничения по размеру

Загружать медиа или отправлять ссылку?

Meta рекомендует загрузить файл и отправлять его media ID. Можно вместо этого отправить ссылку на файл на публичном сервере, но в справочниках Meta по изображениям, видео и документам сказано предпочитать загруженный ID ради производительности, и то же самое говорится в её рекомендациях по пропускной способности для больших объёмов.

В собственной конечной точке Meta загрузка — это POST на /<PHONE_NUMBER_ID>/media с файлом, его MIME-типом и messaging_product=whatsapp, а ответ имеет вид {"id": "<MEDIA_ID>"}. Загруженные файлы шифруются и хранятся 30 дней, если вы не удалите их раньше.

В конечной точке WhatsApp OmniChannels.ai сообщение с медиа принимает либо mediaUrl (публичный HTTPS-URL), либо mediaFile (файл, загружаемый вместе с запросом), а подпись передаётся в content. См. документацию WhatsApp API. Как ваш аккаунт хранит и повторно использует медиа при больших рассылках, уточните у нашей команды.

Сколько действуют media ID?

Meta указывает 30 дней для ID, полученного при загрузке, и 7 дней для ID, полученного во входящем вебхуке. Ссылка для скачивания, возвращаемая по ID, действует 5 минут.

Практические выводы:

• Не кэшируйте media ID на месяцы. Храните исходный файл и загружайте заново, если ID отклонён.
• Скачивайте входящие файлы, как только пришло событие, и храните собственную копию.
• Не сохраняйте полученную ссылку для скачивания: запрашивайте новую, когда она нужна.

Можно ли добавлять подписи к медиа-сообщениям?

Да. Сообщения с изображением, видео и документом принимают необязательную подпись до 1 024 символов, согласно справочникам Meta по сообщениям. Подпись — это обычный текст рядом с файлом.

У аудио и стикеров в этой модели подписи нет. Если к голосовому сообщению нужны слова, отправьте рядом короткое текстовое сообщение. В окне обслуживания клиента подписи пишутся свободно; вне его медиа нужно отправлять внутри одобренного шаблона.

Как работают медиа в шаблонных сообщениях?

В заголовке шаблона может быть изображение, видео или документ, и формат заголовка фиксируется при создании шаблона. Когда вы отправляете шаблон на одобрение, вы прикладываете пример файла, а настоящий файл можно передать уже при отправке.

В нашем API при создании headerFormat может быть IMAGE, VIDEO или DOCUMENT, headerFile передаёт пример, а mediaUrl при отправке заменяет медиа заголовка. Требования к примерам файлов смотрите в документации Meta по шаблонам. См. категории шаблонов и одобрение и примеры шаблонов.

Как скачать медиа, которое прислал клиент?

Входящее медиа приходит вебхуком с media ID; его нужно преобразовать в URL и скачать с авторизацией.

1. Возьмите media ID из события входящего сообщения.
2. Запросите URL медиа для этого ID. В ответе Meta есть url, mime_type, sha256 и file_size.
3. Отправьте GET на этот URL с заголовком Authorization: Bearer <token>. Без токена запрос не пройдёт.
4. Проверьте заголовок Content-Type и значение sha256, затем сохраните файл.
5. При ответе 404 запросите новый URL и повторите; если и это не помогло, обновите токен доступа.

Максимальный размер входящего медиа в Cloud API по данным Meta — 100 МБ. Более крупный файл вызывает вебхук с кодом ошибки 131052; попросите клиента прислать файл поменьше или передать его иным способом. Проверяйте каждый файл антивирусом, прежде чем открывать его внутри компании. См. руководство по вебхукам и уточните у инженера по подключению, как входящее медиа доставляется в вашем аккаунте.

Пример: стоматологическая клиника отправляет отчёты

Клиника «Nile Smile Clinic» (вымышленная) в Каире отправляет талоны на приём и рентгеновские заключения.

1. Талоны на приём — PNG-изображения по 300 КБ с подписью в две строки. Это намного меньше 5 МБ.
2. Отчёты о лечении — PDF по 2–8 МБ с именем report-2026-0381.pdf, отправляются как документы.
3. Видеообзор клиники на 25 МБ слишком велик для видео. Команда перекодирует его в MP4 с H.264/AAC меньше 16 МБ с faststart.
4. Пациенты присылают фото рецептов. Инбокс скачивает каждый файл сразу, потому что входящий ID истекает через 7 дней.
5. Голосовое приветствие экспортировано как моно OGG с Opus, потому что другие варианты OGG отклоняются.

Какие типичные ошибки?

• Оценка только по размеру. Изображение в 3 МБ в неверном цветовом формате или видео с неверным кодеком всё равно не пройдут.
• Несовпадение MIME. Файл .jpg, отдаваемый как application/octet-stream, — классическая причина ошибки 131053.
• Ссылка на медленный или закрытый URL, например истёкшая подписанная ссылка или страница за авторизацией.
• Использование старого media ID. ID истекают через 30 дней.
• Игнорирование срока входящих ID. Файлы клиентов нужно сохранять в течение 7 дней.
• Анимированный WebP как изображение. Он отклоняется; используйте стикер или видео.
• Лимиты меняются. Перед тем как жёстко прописывать проверки, ещё раз сверьтесь со справочником Meta.

Чем помогает OmniChannels.ai

OmniChannels.ai отправляет сообщения WhatsApp с изображениями, видео, аудио, документами и стикерами через один API: по публичной ссылке или с загруженным файлом и с подписью, а медиа и вложения показывает в общем инбоксе. BroadNet — официальный бизнес-провайдер решений Meta (Business Solution Provider), поэтому шаблоны с заголовком-изображением, видео или документом можно создавать и отслеживать по статусу одобрения. Читайте документацию WhatsApp API и ошибки и лимиты или смотрите канал WhatsApp.