Отправка сообщений | Документация для разработчиков
Отправка сообщений
Обновлено: 4 ноября 2025 г
В этом документе описывается, как использовать API для отправки сообщений пользователям WhatsApp.
Типы сообщений
С помощью API можно отправлять следующие типы сообщений.
Сообщения с адресом позволяют легко запросить у пользователей WhatsApp адрес доставки.
В аудиосообщениях отображается значок аудио и ссылка на аудиофайл. Когда пользователь WhatsApp нажимает на значок, клиент WhatsApp загружает и воспроизводит аудиофайл.
Функция «Сообщения контактов» позволяет отправлять пользователям WhatsApp подробную контактную информацию, такую как имена, номера телефонов, физические адреса и адреса электронной почты.
В сообщениях-документах отображается значок документа, ссылка на который ведет к документу, который пользователь WhatsApp может нажать, чтобы загрузить.
В сообщениях с изображениями отображается одно изображение и, при желании, подпись.
Интерактивные сообщения с кнопками призыва к действию (CTA) позволяют сопоставлять любой URL-адрес с кнопкой, поэтому вам не нужно включать длинные или непонятные URL-адреса в текст сообщения.
Интерактивные голосовые сообщения позволяют инициировать звонки в WhatsApp от пользователей.
Интерактивные сообщения в формате Flow позволяют отправлять структурированные сообщения, которые более естественны и удобны для ваших клиентов. Например, вы можете использовать WhatsApp Flow для записи на прием, просмотра товаров, сбора отзывов клиентов, получения новых потенциальных клиентов или чего-либо еще.
Сообщения интерактивного потока описаны в нашем комплекте документации по потокам WhatsApp
Интерактивные сообщения-списки позволяют показывать пользователям WhatsApp список вариантов на выбор.
В интерактивных сообщениях с запросом местоположения отображается текст сообщения и кнопка «Отправить местоположение». Когда пользователь WhatsApp нажимает на эту кнопку, появляется экран обмена местоположением, с помощью которого он может поделиться своим местоположением.
Интерактивные кнопки ответа позволяют отправлять до трех предопределенных вариантов ответа на выбор пользователя.
Сообщения с указанием местоположения позволяют отправлять пользователю WhatsApp координаты широты и долготы определенного места.
В сообщениях WhatsApp отображаются анимированные или статичные изображения-стикеры .
Текстовые сообщения — это сообщения, содержащие только основной текст и, при желании, предварительный просмотр ссылки.
Шаблонные сообщения позволяют отправлять пользователям WhatsApp шаблоны маркетинговых, служебных и аутентификационных сообщений. В отличие от всех других типов сообщений, для отправки шаблонных сообщений не требуется 24-часовое окно ожидания ответа службы поддержки перед отправкой сообщения получателю.
В видеосообщениях отображается миниатюрное изображение видео с возможностью добавления подписи. Когда пользователь WhatsApp нажимает на предварительный просмотр, видео загружается и отображается пользователю.
Реакции — это смайлики-реакции, которые вы можете применить к ранее полученным сообщениям пользователей WhatsApp.
Качество сообщения
Качество ваших сообщений определяется тем, как они были получены пользователями WhatsApp за последние семь дней, и учитывает актуальность сообщений. Оно формируется на основе совокупности сигналов обратной связи от пользователей, таких как блокировки, жалобы, отключение уведомлений, архивирование и причины, по которым пользователи вас блокируют.
Рекомендации по отправке качественных сообщений:
Статус вашего рабочего телефонного номера, рейтинг качества и лимиты сообщений отображаются в WhatsApp Manager > Инструменты учетной записи > Панель « Телефонные номера» .
Следует отметить, что для номеров с высокой интенсивностью трафика нормально испытывать изменения качества в течение коротких промежутков времени (даже в течение нескольких минут).
окна обслуживания клиентов
Каждый раз, когда пользователь WhatsApp отправляет вам сообщение или звонит , запускается 24-часовой таймер, называемый окном обслуживания клиентов (или обновляется, если оно уже было запущено).
Когда окно обслуживания клиентов открыто между вами и пользователем, вы можете отправлять сообщения любого типа . Если окно обслуживания между вами и пользователем не открыто, вы можете отправлять пользователю только шаблонные сообщения, поскольку шаблонные сообщения — это единственный тип сообщений, которые можно отправлять вне окна обслуживания клиентов.
Напоминаем, что вы можете отправлять сообщения только тем пользователям, которые дали согласие на получение сообщений от вас.
Известная проблема: В редких случаях вы можете получить сообщение от пользователя, но не сможете ответить в течение установленного времени службы поддержки. Приносим извинения за неудобства.
Запросы
ПОЧТА /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> /сообщения
{ "messaging_product": "whatsapp", "recipient_type": "<RECIPIENT_TYPE> ", "к": "<WHATSAPP_USER_PHONE_NUMBER> ", "тип": "<MESSAGE_TYPE> ", "<MESSAGE_TYPE> ": {<MESSAGE_CONTENTS> } }
типтип_получателяиндивидуальныйгруппатиптексттекстcurl 'https://graph.facebook.com/v25.0/106540352242922/messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer EAAJB...' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "+16505551234", "type": "text", "text": { "preview_url": true, "body": "По запросу, вот ссылка на наш новейший продукт: https://www.meta.com/quest/quest-3/" } }'
Ответы
Синтаксис ответа
{ "messaging_product": "whatsapp", "contacts": [ { "input": "<WHATSAPP_USER_PHONE_NUMBER> ", "wa_id": "<WHATSAPP_USER_ID> " } ], "messages": [ { "id": "<WHATSAPP_MESSAGE_ID> ", "group_id": "<GROUP_ID> ",<!-- Only included if messaging a group --> "message_status": "<PACING_STATUS> "<!-- Only included if sending a template --> } ] }
Содержание ответа
| | |
| | |
| | |
| | |
| |
Коммерческие сообщения
Коммерческие сообщения — это интерактивные сообщения, используемые совместно с каталогом товаров. См. раздел «Делитесь товарами с клиентами» , чтобы узнать, как использовать сообщения такого типа.
Прочтение уведомлений
Вы можете сообщить пользователю WhatsApp, что прочитали его сообщение отметив его как прочитанное . В этом случае под сообщением пользователя появятся две синие галочки (называемые «уведомления о прочтении»).
Индикаторы ввода
Если ответ пользователю WhatsApp занимает у вас несколько секунд или больше, вы можете сообщить ему о подготовке ответа, отобразив индикатор набора текста и уведомления о прочтении в клиенте WhatsApp:
Контекстные ответы
Вы можете отправить сообщение пользователю WhatsApp в виде контекстного ответа , который цитирует предыдущее сообщение во всплывающем окне:
Это облегчает пользователю понимание того, на какое именно сообщение вы отвечаете.
Вебхуки
Форматы номеров телефонов пользователей WhatsApp
В запросах на отправку сообщений поддерживаются знаки плюса (
+ ), дефисы ( - ), скобки ( , ) и Мы настоятельно рекомендуем указывать как знак плюса, так и код страны при отправке сообщения клиенту. Если знак плюса опущен, к номеру телефона клиента будет добавлен код страны вашего рабочего телефона. Это может привести к недоставке или неправильной доставке сообщений.
Например, если ваша компания находится в Индии (телефонный код страны
91 ) и вы отправляете сообщение на следующий номер телефона клиента в различных форматах:+16315551234+16315551234Правильное число
+1 (631) 555-1234+16315551234Правильное число
(631) 555-1234+916315551234Возможно, неверный номер
1 (631) 555-1234+9116315551234Возможно, неверный номер
Примечание: Для Бразилии и Мексики дополнительный префикс телефонного номера может быть изменен с помощью облачного API. Это стандартное поведение системы и не считается ошибкой.
Кэширование медиафайлов
Если вы используете ссылку (
link ) на медиафайл на вашем сервере (в отличие от идентификатора ( id ) файла, загруженного вами на наши серверы), WhatsApp Cloud API внутренне кэширует этот файл на фиксированный период времени в 10 минут. Мы будем использовать кэшированный файл в последующих запросах на отправку сообщений, если ссылка в последующих запросах на отправку сообщений совпадает со ссылкой в исходном запросе на отправку сообщения.Если вы не хотите, чтобы мы повторно использовали кэшированный ресурс в последующих сообщениях в течение 10 минут, добавьте случайную строку запроса к ссылке на ресурс в полезной нагрузке нового запроса на отправку сообщения. Мы будем рассматривать это как новый ресурс, получим его с вашего сервера и кэшируем на 10 минут.
Например:
https://link.to.media/sample.jpg — ресурс получен и кэширован в течение 10 минут.Ссылка на ресурс в 2D-файле, отправленная в запросе на сообщение: https://link.to.media/sample.jpg - использовать кэшированный ресурс.Ссылка на ресурс в третьем запросе на отправку сообщения: https://link.to.media/sample.jpg?abc123 - ресурс получен и кэширован в течение 10 минут.
Последовательность доставки нескольких сообщений
При отправке серии сообщений порядок их доставки не гарантирует совпадения с порядком ваших API-запросов. Если вам необходимо обеспечить последовательность доставки сообщений, подтвердите получение
доставки в сообщений о статусе перед отправкой следующего сообщения в вашей последовательности.Время жизни сообщения (TTL)
Если нам не удаётся доставить сообщение пользователю WhatsApp, мы будем повторять попытку доставки в течение периода времени, известного как время жизни (TTL) или срок действия сообщения.
TTL по умолчанию
Настройка TTL для шаблонов
Вы можете настроить значение TTL по умолчанию для шаблонов аутентификации и служебных шаблонов, а также для маркетинговых шаблонов, отправляемых с помощью API маркетинговых сообщений для WhatsApp. Подробнее об этом см. в нашем документе «Time-to-live»
При превышении TTL: сообщения отбрасываются
Сообщения, которые не могут быть доставлены в течение заданного по умолчанию или пользовательского времени жизни (TTL), отбрасываются.
до истечения TTL вы не получили веб-перехватчик сообщений о статусе с пометкой
« доставлено» Если отправка сообщения завершается неудачей (
статус установлен на "неудачно "), может возникнуть небольшая задержка перед получением веб-перехватчика, поэтому, возможно, стоит предусмотреть небольшой буфер, прежде чем считать, что сообщение было отброшено.Поиск неисправностей
Если у вас возникли проблемы с доставкой сообщений, см. раздел «Сообщение не доставлено» .