Файлы и голосовые
в WhatsApp через API

Подготовьте локальный файл

Войдите в кабинет WatsyApp, подключите свой номер по QR-инструкции и дождитесь состояния «Активен». В разделе «Интеграция API» возьмите личный API-ключ. Передавайте его только со своего сервера в заголовке Authorization: Bearer YOUR_API_KEY; не помещайте ключ в JavaScript публичного сайта.

Во всех примерах используются заглушки. Замените RECIPIENT_DIGITS номером получателя в международном формате, 7–15 цифр, без плюса, пробелов и скобок. Команды рассчитаны на Bash. Страница ничего не отправляет сама; выполнение команды с действующими параметрами отправит сообщение.

Используйте один файл размером не более 20 × 1024 × 1024 байт (20 МиБ). Лимит относится к загружаемому вложению WatsyApp, а не ко всем возможностям WhatsApp. Метод принимает байты локального файла, не ссылку на скачивание.

PDF и документы: POST /api/send

Запрос — multipart/form-data. Обязательны chatId и, для отправки вложения, file. Поле text необязательно; для документа оно становится подписью. Канал определяется API-ключом, поэтому channelId в этом методе не требуется.

curl --request POST 'https://watsyapp.com/api/send' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'chatId=RECIPIENT_DIGITS' \
  --form 'text=Документ по вашему запросу' \
  --form 'file=@./document.pdf;type=application/pdf'

Не задавайте общий заголовок Content-Type: multipart/form-data вручную: curl добавит boundary. Параметр type=application/pdf внутри поля файла задаёт MIME-тип самого вложения.

{
  "messageId": "MESSAGE_ID",
  "chatId": "RECIPIENT_DIGITS"
}

Сохраните messageId вместе с ID операции своей системы. Ответ 200 подтверждает выполнение отправки, но не доставку и не прочтение. Проверьте результат в диалоге и на тестовом телефоне получателя.

Если соединение оборвалось или клиент дождался тайм-аута, результат может быть неизвестен. В текущем контракте нет ключа идемпотентности: автоматический повтор способен отправить дубль. Сначала проверьте диалог и журнал своей системы; повторяйте только после выяснения результата.

Изображения, видео и обычное аудио

Способ отправки зависит от MIME-типа загрузки: image/* — картинка, video/* — видео, audio/* — аудио. Остальные типы уходят как документ с исходным именем файла. Указывайте MIME-тип, соответствующий содержимому.

curl --request POST 'https://watsyapp.com/api/send' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'chatId=RECIPIENT_DIGITS' \
  --form 'text=Фото по вашему запросу' \
  --form 'file=@./photo.jpg;type=image/jpeg'

Подпись text применяется к изображениям, видео и документам. В текущей реализации обычное аудио и голосовое отправляются без подписи: при необходимости отправьте пояснение отдельным текстовым сообщением. Произвольный кодек не гарантирует воспроизведение на телефоне; проверьте тестовое вложение на устройстве получателя.

Голосовое сообщение: type=voice

Чтобы отправить аудио как голосовое, добавьте отдельное поле формы type=voice. Это другой параметр, чем MIME-тип файла. Сервер преобразует загруженное аудио в OGG/Opus и передаст его как PTT. Обычная загрузка аудиофайла без этого поля отправит аудио, а не голосовое.

curl --request POST 'https://watsyapp.com/api/send' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --form 'chatId=RECIPIENT_DIGITS' \
  --form 'type=voice' \
  --form 'file=@./recording.mp3;type=audio/mpeg'

Конвертация может завершиться ошибкой, если исходник повреждён, не содержит подходящего аудио или превышено время обработки. Ограничение загрузки 20 МиБ действует и для исходного голосового файла.

Проверка ошибок и повторов

• 401: личный ключ отсутствует или не принят.
• 413: проверьте размер и число файлов. Загрузчик разрешает только одно поле файла с именем file; ошибки multipart тоже могут вернуть 413.
• 400: проверьте получателя, подключение, наличие файла и возможность преобразовать аудио. Читайте поле error.
• Ошибка curl до отправки: проверьте путь и права чтения локального файла; знак @ перед путём означает загрузку его содержимого.

Не используйте JSON-поле contentUri в /v3/message: оно возвращает 422. Нет публичного webhook для подтверждений. API WatsyApp использует QR-подключение; это не контракт Meta Cloud API/WABA.