> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Руководство по интеграции 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 для: 1. Установки **Max Price** и **множителя для страны (Country multiplier)** в шаблоне маркетингового сообщения 2. Опционального применения **множителя для отдельного сообщения** при отправке сообщения 3. Получения **итоговой стоимости с помощью вебхуков статуса сообщений** 4. Оценки объема доставки и затрат при различных уровнях **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. Рекомендуемый процесс интеграции 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](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 Пример запроса ```bash highlight={11-23} theme={"theme":{"light":"github-light","dark":"github-dark"}} 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`. ```json highlight={6-18} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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}](https://docs.ycloud.com/reference/whatsapp_template-edit-by-name-and-language) * Сценарий использования: корректировка максимальной цены ### 5.2 Параметры запроса и пример См. раздел [Создание шаблона с Max Price](#4-create-a-template-with-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](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 Пример запроса ```bash highlight={8-9} theme={"theme":{"light":"github-light","dark":"github-dark"}} 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` является ориентировочной ценой, а не окончательным списанием. ```json highlight={18} theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 ```bash highlight={28-30} theme={"theme":{"light":"github-light","dark":"github-dark"}} 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` | Пример запроса: ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 Пример ответа ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 } ] } ``` Интерпретация: 1. Если максимальная цена (Max Price) за сообщение составляет `395 / 1000 USD = USD 0.395`, то для пакета из 1000 получателей расчетный диапазон доставляемости составит `4.8% to 23.4%`, а ориентировочная стоимость — примерно `USD 344.46 to USD 396`. 2. Если максимальная цена (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 возвращает расчетную цену, а не окончательную стоимость. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.