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

1. Обзор

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

Установка параметров Max Price и Country multiplier для шаблона маркетинговых сообщений
Опциональное применение множителя для конкретного сообщения при отправке сообщения
Получение итоговой стоимости через Webhook со статусом сообщения
Оценка объема доставки и затрат при различных уровнях 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 = maxBid шаблона x 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) x 1,2(множитель для сообщения) = 0,096 USD
Bob	0,5	MY	0,1(maxBid) * 1,3(MY множитель) * 0,5(множитель для сообщения)= 0,065 USD
Jane	0,7	SG	0,1(maxBid) x 1(множитель по умолчанию) x 0,7(множитель для сообщения) = 0,07 USD
Jack	None	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}
Сценарий использования: корректировка предельной цены (Max Price)

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. Окончательные списания и вебхуки со статусом сообщений

7.1 Вебхук-событие

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

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

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

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, для пакета из 1 000 получателей расчетный диапазон показателя доставки составляет 4.8% to 23.4%, а расчетный диапазон стоимости — примерно USD 344.46 to USD 396.
Когда максимальная цена (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 возвращает расчетную цену, а не окончательную стоимость.

​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. Окончательные списания и вебхуки со статусом сообщений

​7.1 Вебхук-событие

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

​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. Окончательные списания и вебхуки со статусом сообщений

7.1 Вебхук-событие

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

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

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

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

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

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

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

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

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

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