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

1. Обзор

Чтобы помочь бизнесу лучше контролировать и оптимизировать расходы на маркетинговые рассылки в WhatsApp, YCloud поддерживает новые возможности ценообразования, представленные Meta для Marketing Messages API в 2026 году, включая Max Price и инструмент Reach Estimation Tool. С помощью API YCloud компании могут задавать максимальную цену, которую они готовы платить за каждое доставленное маркетинговое сообщение в WhatsApp, и корректировать ценовую стратегию в зависимости от бюджета кампании и целей по доставке. При установке Max Price компания Meta списывает за каждое доставленное сообщение указанную цену или меньшую сумму. Перед отправкой компании также могут использовать инструмент Reach Estimation Tool, чтобы оценить прогнозируемый объем доставки и расходы при различных уровнях Max Price. В этом руководстве объясняется, как использовать API YCloud, чтобы:
  1. Задавать Max Price и Country multiplier для шаблона маркетингового сообщения
  2. При необходимости применять множитель для отдельного сообщения при отправке
  3. Получать итоговую стоимость через вебхуки статуса сообщений
  4. Оценивать объем доставки и расходы при различных уровнях Max Price перед отправкой

2. Основные концепции

2.1 Что такое Max Price?

Max Price — это максимальная сумма, которую бизнес готов заплатить за каждое успешно доставленное маркетинговое сообщение в WhatsApp. Если установлен Max Price, Meta списывает за доставку эту сумму или меньше. Фактическая стоимость не превысит заданный ценовой лимит. В зависимости от цели маркетинговой кампании бизнес может установить Max Price на уровне опубликованного тарифа Meta, ниже или выше него: Max Price — это ценовой потолок, а не фиксированная плата. Установка Max Price не означает, что каждое доставленное сообщение будет тарифицироваться по этой цене. Стоимость каждого сообщения рассчитывается динамически и может быть равна установленному Max Price или ниже его.

2.2 Как настроить Max Price

2.2.1 Установка максимальной цены в шаблоне Вы можете задать фиксированный Max Price (maxBid) для шаблона и настроить различные множители (countryPriceAdjustments.multiplier) для разных стран или регионов. Например, предположим, что параметр maxBid установлен на 0,10 USD, с множителем 0,8× для Индии и множителем 1,3× для Малайзии:
  • Когда шаблон используется для отправки сообщения в Индию, Max Price на уровне шаблона составляет 0,10 USD × 0,8 = 0,08 USD.
  • Когда шаблон используется для отправки сообщения в Малайзию, Max Price на уровне шаблона составляет 0,10 USD × 1,3 = 0,13 USD.
  • При отправке сообщения по шаблону в любую другую страну Max Price на уровне шаблона составляет 0,10 USD.
2.2.2 Корректировка множителя при отправке шаблонного сообщения При отправке сообщения с использованием шаблона с Max Price вы можете применить множитель для отдельного сообщения больше 0, чтобы увеличить или уменьшить эффективный Max Price для конкретного сообщения. 2.2.3 Расчет эффективного Max Price
Эффективный Max Price = maxBid шаблона x countryPriceAdjustments.multiplier шаблона x per_message_bid_multiplier
Пример: Для шаблона с maxBid: "0.1" в USD множители для стран 0.8 для Индии и 1.3 для Малайзии формируют следующие эффективные ценовые потолки: Суммы указываются в валюте расчетов вашего аккаунта YCloud. Для стран без переопределения используется множитель 1. Опустите весь объект bidSpec на уровне сообщения, чтобы использовать множитель для отдельного сообщения, равный 1.

2.3 Правила динамической тарификации

Цена каждого успешно доставленного сообщения рассчитывается динамически для его получателя:
  • Параметр Max Price, настроенный в шаблоне, представляет собой только максимальную сумму, которую компания готова заплатить.
  • Окончательная стоимость доставленного сообщения является динамической; Meta списывает за доставку сумму по этой максимальной цене или ниже.
  • Для разных получателей в одной и той же рассылке фактическая стоимость сообщения может отличаться.
  • За недоставленные сообщения плата за доставку не взимается.
  • Параметр Max Price влияет на ставки и возможность доставки, но не гарантирует ее. На фактические результаты также могут влиять торги в реальном времени, статус получателя и проверки соответствия требованиям со стороны Meta.

2.4 Что такое инструмент оценки охвата?

Инструмент оценки охвата (Reach Estimation Tool) помогает компаниям подобрать подходящее значение Max Price. Перед отправкой компании могут использовать эндпоинт оценки, чтобы просмотреть предполагаемый объем доставки и диапазон затрат при различных уровнях Max Price, а затем выбрать стратегию ценообразования с учетом целей кампании и бюджета. Оценки предоставляются исключительно в целях планирования и не гарантируют фактических результатов доставки или окончательных сумм в счетах. На фактические результаты могут влиять торги в реальном времени, статус получателя и проверки соответствия требованиям со стороны Meta.

3. Рекомендуемый процесс интеграции

  1. Вызовите reachEstimate перед отправкой, чтобы сравнить ожидаемую эффективность при различных уровнях цен.
  2. Настройте Max Price на уровне шаблона с помощью bidSpec при создании маркетингового шаблона.
  3. При необходимости передайте per_message_bid_multiplier при отправке сообщения, чтобы скорректировать Max Price для конкретного получателя.

4. Создание шаблона с Max Price

4.1 Эндпоинт

Добавьте объект bidSpec при создании шаблона маркетингового сообщения.
  • Эндпоинт: https://api.ycloud.com/v2/whatsapp/templates
  • Сценарий использования: установка Max Price на уровне шаблона при создании маркетингового шаблона

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

Объект bidSpec содержит следующие поля:

4.3 Пример запроса

4.4 Правила

  • Только шаблоны MARKETING поддерживают Max Price.
  • maxBid может быть ниже опубликованного тарифа. Передавайте суммы и множители в виде десятичных строк, а не чисел JSON.
  • Если bidSpec опущен, в шаблоне используется стандартная тарификация по опубликованным ценам.
  • Создание шаблона с bidSpec: {} недопустимо. Укажите действительное значение maxBid при создании с bidSpec.

4.5 Пример ответа

После создания шаблона ответ содержит объект шаблона и его конфигурацию bidSpec.

5. Добавление, обновление или очистка Max Price

5.1 Эндпоинт

Используйте PATCH /v2/whatsapp/templates/{wabaId}/{name}/{language} для редактирования маркетингового шаблона, в том числе созданного без Max Price.

5.2 Выбор поведения при редактировании

Объект, свойства которого имеют значение null, например {"maxBid": null, "countryPriceAdjustments": null}, также сбрасывает настройки. Пустые строки, пустые массивы и другие свойства со значениями, отличными от null, не считаются пустой конфигурацией. Например, передача {"countryPriceAdjustments": []} без валидного maxBid недопустима. Чтобы добавить или обновить Max Price, используйте поля из раздела Создание шаблона с Max Price. Укажите полный список стран, который хотите сохранить. Переданный список заменяет сохраненный локально список; если его опустить или передать пустой список, переопределения для стран, уже сохраненные Meta, явно удалены не будут. Чтобы удалить все настройки ставок, отправьте bidSpec: {}. Включите каждый компонент, который хотите сохранить. В следующем примере сбрасывается конфигурация ставок и сохраняется тело:

5.3 Правила

  • Добавление, обновление и очистка Max Price выполняются по существующему процессу редактирования шаблонов и валидации Meta. Редактировать можно только шаблоны в статусе APPROVED, REJECTED или PAUSED.
  • Передавайте компоненты, которые хотите сохранить, даже если меняются только параметры цены. Успешное редактирование проходит стандартный процесс проверки и синхронизации статуса.
  • После успешной очистки ответ шаблона больше не содержит объект bidSpec. Если Meta или локальное сохранение завершается ошибкой, эндпоинт возвращает ошибку.

6. Установка множителя ставки для конкретного сообщения при отправке

6.1 Эндпоинт

Добавьте объект bidSpec на уровне сообщения в любой из эндпоинтов отправки:
  • POST /v2/whatsapp/messages/sendDirectly отправляет сообщение синхронно.
  • POST /v2/whatsapp/messages ставит сообщение в очередь для асинхронной обработки.
Используйте множитель с маркетинговым шаблоном Max Price, отправляемым через Marketing Messages Lite. Вызов эндпоинта sendDirectly сам по себе не выбирает отдельный продукт Utility или Authentication Direct Send.

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

Объект bidSpec на уровне сообщения содержит следующее поле:

6.3 Пример запроса

6.4 Правила

  • per_message_bid_multiplier должен быть больше 0 и не более 999.999, максимум с тремя знаками после запятой. Значение больше 1 увеличивает эффективный Max Price, а значение между 0 и 1 уменьшает его.
  • Множитель применяется только к маркетинговому шаблону, для которого включен Max Price через bidSpec.
  • Если запрос сообщения содержит объект bidSpec, per_message_bid_multiplier обязателен. В отличие от редактирования шаблона, значение bidSpec: {} в сообщении недопустимо. Чтобы использовать множитель по умолчанию 1, опустите весь объект bidSpec.

6.5 Ответ

Эндпоинт отправки продолжает использовать стандартный ответ сообщения WhatsApp. Передача bidSpec не влечет за собой отдельную структуру ответа. Когда возвращаемый статус равен accepted, totalPrice является расчетной ценой. В этом примере у получателя из США нет переопределения для страны, поэтому 0.05 x 1 x 1.1 = 0.055 USD. Для окончательной стоимости используйте вебхук delivered/read.

7. Итоговая стоимость и Webhook статуса сообщений

7.1 Событие Webhook

YCloud отправляет событие Webhook whatsapp.message.updated при изменении статуса сообщения WhatsApp. Для сообщений, отправленных с использованием Max Price, Webhook указывает режим тарификации и сообщает итоговую стоимость после доставки сообщения.

7.2 Пример полезной нагрузки Webhook

В этом примере:
  • totalPrice является итоговой стоимостью, так как статус сообщения равен delivered или read.
  • pricingCategory: marketing_lite_bidding определяет категорию ценообразования Max Price.
  • bidPricingFlag: true подтверждает, что сообщение было отправлено с использованием тарификации Max Price.

8. Оценка доставки и стоимости перед отправкой

8.1 Эндпоинт

  • Эндпоинт: GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate
  • Сценарий использования: используйте эндпоинт оценки охвата перед отправкой, чтобы просмотреть расчетные диапазоны доставки и стоимости при различных уровнях цен.

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

Пример запроса:

8.3 Структура ответа

Каждый элемент в estimates содержит:

8.4 Пример ответа

Интерпретация:
  1. Когда Max Price за сообщение составляет 395 / 1000 USD = USD 0.395, для партии из 1 000 получателей расчетный диапазон доли доставок составляет 4.8% to 23.4%, а расчетный диапазон стоимости — приблизительно USD 344.46 to USD 396.
  2. Когда Max Price за сообщение составляет 495 / 1000 USD = USD 0.495, для партии из 1 000 получателей расчетный диапазон доли доставок составляет 6.3% to 26.3%, а расчетный диапазон стоимости — приблизительно USD 353.067 to USD 429.597.

Часто задаваемые вопросы

Могу ли я узнать фактическую стоимость доставки конкретному получателю перед отправкой?

Нет. Стоимость доставки каждому получателю динамическая, и ее нельзя узнать заранее. Бизнесу достаточно лишь установить максимальную цену, которую он готов заплатить. Плата за успешно доставленное сообщение взимается по его фактической цене доставки, которая не превысит действующий Max Price.

Почему фактические результаты доставки отличаются от расчетных?

Эндпоинт расчета предоставляет только справочные значения. На фактические результаты могут влиять торги в реальном времени, статус получателя и проверки соответствия требованиям Meta. Если расхождение существенно, обратитесь за помощью в YCloud.

Будет ли возвращена фактическая стоимость после доставки сообщения?

Да. Когда статус сообщения — delivered или read, totalPrice представляет собой окончательную плату на основе фактической цены доставки для данного получателя. Когда сообщение только принято или его статус — sent, YCloud возвращает ориентировочную цену, а не окончательную стоимость.