Руководство по интеграции Max Price

Эта функция в настоящее время находится в бета-версии. Чтобы запросить доступ, свяжитесь с YCloud.

1. Обзор

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

Установки Max Price и множителя для страны (Country multiplier) в шаблоне маркетингового сообщения
Опционального применения множителя для отдельного сообщения при отправке сообщения
Получения итоговой стоимости с помощью вебхуков статуса сообщений
Оценки объема доставки и затрат при различных уровнях Max Price перед отправкой

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

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

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

Ценовая стратегия	Цель	Ожидаемый результат
Равна опубликованному тарифу	Контролировать расходы, сохраняя показатели доставки на уровне существующих кампаний в WhatsApp	Потенциально более низкие затраты при сохранении аналогичного уровня доставки
Ниже опубликованного тарифа	Охватить подходящие когорты клиентов с меньшими затратами	Снизить максимально приемлемую цену за сообщение, хотя объем доставки может соответственно измениться
Выше опубликованного тарифа	Повысить показатели доставки во время праздников, крупных акций или пиковых периодов продаж	Повысить конкурентоспособность и увеличить вероятность доставки большего количества сообщений

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 = Template maxBid x Template countryPriceAdjustments.multiplier x per_message_bid_multiplier

Пример: Вы создали шаблон, и настройки Max Price на уровне шаблона следующие:

maxBid: 0.1 USD,
countryPriceAdjustments.multiplier:
- IN: 0.8x
- MY: 1.3x

Затем есть 4 получателя; вы отправляете им сообщения с различными множителями для отдельных сообщений**,** эффективные значения Max Price рассчитываются следующим образом:

Получатели	Примененный множитель для сообщения	Страна	Эффективный Max Price
Mike	1.2	IN	0.1(maxBid) x 0.8(IN multiplier) x 1.2(per-message multiplier) = 0.096 USD
Bob	0.5	MY	0.1(maxBid) * 1.3(MY multiplier) * 0.5(per-message multiplier)= 0.065 USD
Jane	0.7	SG	0.1(maxBid) x 1(множитель по умолчанию) x 0.7(множитель для сообщения) = 0.07 USD
Jack	Нет	IN	0.1(maxBid) * 0.8(множитель для IN ) * 1(множитель по умолчанию)= 0.08 USD

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

Стоимость каждого успешно доставленного сообщения рассчитывается динамически для каждого получателя:

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

2.4 Что такое инструмент оценки охвата (Reach Estimation Tool)?

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

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

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

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

4.1 Эндпоинт

Добавьте объект bidSpec при создании маркетингового шаблона сообщений.

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

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

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

Поле	Тип	Обязательное	Описание
`maxBid`	string	Обязательно, если указан `bidSpec`	Максимальная цена, допустимая шаблоном. По умолчанию валюта совпадает с вашей расчетной валютой в YCloud.
`countryPriceAdjustments`	string	Нет	Сопоставление страны назначения с множителем ставки. Для стран, не указанных в списке, используется множитель `1.0` (исходный `maxBid`). До 50 записей. До 50 записей.
`countryPriceAdjustments.countryCode`	string	Обязательно, если указан `countryPriceAdjustments`	Ключи должны быть действительными двухбуквенными кодами стран по стандарту ISO 3166-1 alpha-2 (например, `MX`, `IN`, `BR`).
`countryPriceAdjustments.multiplier`	string	Обязательно, если указан `countryPriceAdjustments`	Каждый множитель должен быть больше `0` и не более `10`.

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

curl --request POST \
  --url 'https://api.ycloud.com/v2/whatsapp/templates' \
  --header 'X-API-Key: {{YOUR_API_KEY}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "category": "MARKETING",
    "wabaId": "{{YOUR_WABA_ID}}",
    "name": "market",
    "language": "en",
    "bidSpec": {
      "maxBid": "0.123",
      "countryPriceAdjustments": [
        {
          "countryCode": "CN",
          "multiplier": "1.9"
        },
        {
          "countryCode": "ID",
          "multiplier": "1.3"
        }
      ]
    },
    "components": [
      {
        "type": "BODY",
        "text": "Hi, Black Friday is coming!"
      }
    ]
  }'

4.4 Правила

maxBid должно быть больше 0 и может быть ниже опубликованного тарифа.
Если bidSpec опущено, шаблон использует стандартное ценообразование по опубликованному тарифу.

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

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

{
  "officialTemplateId": "1763024734605057",
  "wabaId": "{{YOUR_WABA_ID}}",
  "name": "marketing_friday",
  "language": "en",
  "bidSpec": {
    "maxBid": "0.123",
    "countryPriceAdjustments": [
        {
          "countryCode": "CN",
          "multiplier": "1.9"
        },
        {
          "countryCode": "ID",
          "multiplier": "1.3"
        }
      ]
  },
  "messageSendTtlSeconds": -1,
  "components": [
    {
      "type": "BODY",
      "text": "Hi, Black Friday is coming!"
    }
  ],
  "category": "MARKETING",
  "status": "PENDING",
  "qualityRating": "UNKNOWN",
  "createTime": "2026-08-12T15:18:42.356Z",
  "updateTime": "2026-08-12T15:18:42.356Z",
  "ctaUrlLinkTrackingOptedOut": true
}

5. Обновление Max Price в шаблоне

5.1 Эндпоинт

Добавьте объект bidSpec при обновлении маркетингового шаблона сообщений.

Эндпоинт: https://api.ycloud.com/v2/whatsapp/templates/{wabaId}/{name}/{language}
Сценарий использования: корректировка максимальной цены

5.2 Параметры запроса и пример

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

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

5.3 Правила

Вы не можете добавить bidSpec к существующему шаблону, который был создан без него. Вам необходимо создать новый шаблон с добавлением bidSpec.
Одобренные шаблоны: до 100 изменений в час, 2400 в день. Редактирование содержимого по-прежнему ограничено 1 разом в день и 10 разами за 30 дней.
Отклоненные или приостановленные шаблоны: неограниченное количество правок

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

6.1 Эндпоинт

Добавьте объект bidSpec при прямой отправке сообщения.

Эндпоинт: https://api.ycloud.com/v2/whatsapp/messages/sendDirectly
Сценарий использования: корректировка действующей Max Price для отдельного получателя

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

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

Поле	Тип	Обязательное	Описание
`per_message_bid_multiplier`	string	Условное	Множитель, применяемый к действующей Max Price на уровне шаблона для этого сообщения. Должен быть больше 0 и поддерживает до трех знаков после запятой. Если `bidSpec` включен в запрос, это поле является обязательным. Чтобы использовать множитель по умолчанию `1`, опустите весь объект `bidSpec`.

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

curl --request POST \
  --url 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
  --header 'X-API-Key: {{YOUR_API_KEY}}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "template",
    "bidSpec": {
      "per_message_bid_multiplier": "1.2"
    },
    "template": {
      "language": {
        "code": "en"
      },
      "name": "marketing_friday"
    },
    "from": "+1555*****",
    "to": "+62*****"
  }'

6.4 Правила

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

6.5 Ответ

Конечная точка отправки продолжает использовать стандартный ответ сообщения WhatsApp. Передача bidSpec не создает отдельную структуру ответа. Когда возвращаемый статус равен accepted, totalPrice является ориентировочной ценой, а не окончательным списанием.

{
  "id": "6a7c922697330900cf11ca2f",
  "wamid": "wamid.HBgNODYxNTA2NzExMDI0NBUCABEYEkE1REJGMkIzOTMwQ0VENUIyMAA=",
  "status": "accepted",
  "from": "+1555*****",
  "to": "+62*****",
  "wabaId": "{{YOUR_WABA_ID}}",
  "type": "template",
  "template": {
    "name": "marketing_friday",
    "language": {
      "code": "en"
    }
  },
  "createTime": "2026-08-12T15:32:54.571Z",
  "updateTime": "2026-08-12T15:32:55.228Z",
  "totalPrice": 0.1845,
  "pricingCategory": "marketing_lite_bidding",
  "currency": "USD",
  "regionCode": "ID",
  "bizType": "whatsapp"
}

7. Окончательные списания и Webhook статуса сообщений

7.1 Событие Webhook

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

Поле	Новое поле/значение	Описание
`bidPricingFlag`	Новое поле	Boolean. `true` указывает, что сообщение было отправлено с использованием ценообразования Max Price; `false` указывает на стандартное ценообразование по опубликованным тарифам
`pricingCategory`	Новое значение	Маркетинговые сообщения Max Price используют `marketing_lite_bidding`
`totalPrice`	Существующее поле	Динамическая цена сообщения. Значение может отличаться в зависимости от получателя. Оно становится окончательным списанием, когда статус сообщения равен `delivered` или `read`

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

curl --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "evt_6a7d30d9c038963ead5945f3",
    "type": "whatsapp.message.updated",
    "apiVersion": "v2",
    "createTime": "2026-08-13T02:50:01.057Z",
    "whatsappMessage": {
      "id": "6a7d30c92733962aed9f0fda",
      "wamid": "wamid.HBgLNTE5OTc5NTMwOTQVAgARGBI5MUJBNTE0Qjk4Q0E5NTIzMDgA",
      "status": "read",
      "from": "+1555***",
      "to": "+62***",
      "wabaId": "{{YOUR_WABA_ID}}",
      "recipient": "ID.12*******",
      "type": "template",
      "template": {
        "name": "marketing_friday",
        "language": {
          "code": "en"
        },
        "components": []
      },
      "createTime": "2026-08-13T02:49:45.403Z",
      "sendTime": "2026-08-13T02:49:50.000Z",
      "deliverTime": "2026-08-13T02:49:50.000Z",
      "readTime": "2026-08-13T02:50:00.000Z",
      "totalPrice": 0.0703,
      "pricingCategory": "marketing_lite_bidding",
      "bidPricingFlag": true,
      "pricingType": "regular",
      "pricingModel": "PMP",
      "currency": "USD",
      "regionCode": "ID",
      "bizType": "whatsapp",
      "recipientUserId": "ID.12*******"
    }
  }'

В этом примере:

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

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

8.1 Конечная точка

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

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

Параметр	Тип	Обязательно	Описание
`wabaId`	string	Да	Идентификатор WhatsApp Business Account
`targetCountry`	string	Да	Код целевой страны. Ключи должны быть действительными двухбуквенными кодами стран стандарта ISO 3166-1 alpha-2 (например, `MX`, `IN`, `BR`).. Ключи должны быть действительными двухбуквенными кодами стран стандарта ISO 3166-1 alpha-2 (например, `MX`, `IN`, `BR`).
`dateInterval`	string	Нет	Период ретроспективного анализа исторических данных, используемых для формирования оценок. Один из вариантов: `L1D` (последний 1 день), `L7D` (последние 7 дней), `L14D` (последние 14 дней), `L28D` (последние 28 дней). По умолчанию `L28D`

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

GET /v2/whatsapp/businessAccounts/{wabaId}/reachEstimate?targetCountry=MX&dateInterval=L7D

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

Поле	Тип	Описание
`waba_currency`	string	Валюта WABA
`estimates`	array	Список расчетных уровней цен
`dateInterval`	string	Период ретроспективного анализа исторических данных, используемых для формирования оценок

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

Поле	Тип	Описание
`bid_amount`	number	Максимальная сумма, которую бизнес готов заплатить за партию из 1 000 получателей
`users`	number	Количество целевых получателей; в настоящее время фиксировано на уровне `1000`
`deliveries_lower_bound`	string	Расчетное минимальное количество доставленных сообщений на 1 000 получателей
`deliveries_upper_bound`	string	Расчетное максимальное количество доставленных сообщений на 1 000 получателей
`cost_lower_bound`	number	Расчетная минимальная стоимость для партии
`cost_upper_bound`	number	Расчетная максимальная стоимость для партии

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

{
  "waba_currency": "USD",
  "dateInterval": "L7D",
  "estimates": [
    {
      "bid_amount": 395,
      "users": 1000,
      "deliveries_lower_bound": 48,
      "deliveries_upper_bound": 234,
      "cost_lower_bound": 344.46,
      "cost_upper_bound": 396
    },
    {
      "bid_amount": 495,
      "users": 1000,
      "deliveries_lower_bound": 63,
      "deliveries_upper_bound": 263,
      "cost_lower_bound": 353.067,
      "cost_upper_bound": 429.597
    }
  ]
}

Интерпретация:

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

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

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

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

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

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

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

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

​1. Обзор

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

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

​2.2 Как установить Max Price

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

​2.4 Что такое инструмент оценки охвата (Reach Estimation Tool)?

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

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

​4.1 Эндпоинт

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

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

​4.4 Правила

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

​5. Обновление Max Price в шаблоне

​5.1 Эндпоинт

​5.2 Параметры запроса и пример

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

​5.3 Правила

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

​6.1 Эндпоинт

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

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

​6.4 Правила

​6.5 Ответ

​7. Окончательные списания и Webhook статуса сообщений

​7.1 Событие Webhook

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

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

​8.1 Конечная точка

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

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

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

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

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

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

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

1. Обзор

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

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

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

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

2.4 Что такое инструмент оценки охвата (Reach Estimation Tool)?

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

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

4.1 Эндпоинт

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

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

4.4 Правила

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

5. Обновление Max Price в шаблоне

5.1 Эндпоинт

5.2 Параметры запроса и пример

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

5.3 Правила

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

6.1 Эндпоинт

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

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

6.4 Правила

6.5 Ответ

7. Окончательные списания и Webhook статуса сообщений

7.1 Событие Webhook

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

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

8.1 Конечная точка

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

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

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

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

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

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

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