Руководство по интеграции тарификации сообщений WhatsApp

YCloud предоставляет информацию о стоимости каждого сообщения через вебхуки обновления статуса сообщений WhatsApp. В этом руководстве описываются событие подписки, поля тарификации, правила списания и моменты, когда цены на сообщения становятся окончательными. YCloud взимает плату только за исходящие сообщения WhatsApp (сообщения, отправленные вашей компанией пользователям). Входящие сообщения бесплатны.

1. Событие подписки

YCloud отправляет обновления статуса и стоимости сообщений через событие whatsapp.message.updated. Подписки доступны в разделе Developers → Webhook в консоли YCloud. Следующий запрос создает подписку через API. Справочную информацию о конечной точке см. в разделе Create a webhook endpoint:

POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY

{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": ["whatsapp.message.updated"],
  "status": "active"
}

url указывает конечную точку получения вебхука. Обработка событий и проверка подписи описаны в Webhook Integration Guide.

2. Поля тарификации

Информация о тарификации содержится в объекте whatsappMessage обратного вызова:

Поле	Описание
`pricingModel`	Всегда `PMP`, что означает оплату за каждое сообщение.
`pricingType`	Платный или бесплатный тип тарификации сообщения.
`pricingCategory`	Категория тарификации сообщения, например `marketing`, `utility`, `authentication`, `service` или `referral_conversion` (бесплатная точка входа). Если `pricingType=free_entry_point`, это поле имеет значение `referral_conversion`.
`totalPrice`	Сумма, переданная YCloud для этого сообщения.
`currency`	Валюта суммы, например `USD`, взятая из настроек валюты арендатора.

Другие поля описаны в разделе Retrieve a message.

3. Правила тарификации

3.1 Окончательная фиксация цены

YCloud передает расчетные или окончательные цены в зависимости от статуса сообщения:

Статус сообщения	Значение цены
`accepted` / `sent`	Расчетная цена.
`delivered` / `read`	Окончательная цена. Для биллинга используются `totalPrice` и `currency`, переданные на этом этапе.
`failed`	Ошибка отправки. YCloud не взимает плату за сообщение.

3.2 Платные и бесплатные типы тарификации

YCloud передает следующие три типа тарификации через pricingType:

`pricingType`	Значение
`regular`	Стандартная платная тарификация. Фактическая сумма, переданная YCloud, указана в `totalPrice`.
`free_customer_service`	Бесплатное сообщение в рамках окна обслуживания клиентов. YCloud сообщает о сумме `0`. В соответствии с обновлением тарифов WhatsApp, вступающим в силу 1 октября 2026 года, каждый рабочий номер телефона получает 1000 бесплатных доставленных сервисных сообщений в месяц. Индивидуальные сервисные сообщения в пределах этого лимита продолжают использовать данный тип тарификации.
`free_entry_point`	Сообщение бесплатной точки входа, подпадающее под действие правил 72-часового бесплатного окна. Его `pricingCategory` имеет значение `referral_conversion`, и YCloud сообщает о сумме `0`.

С 1 октября 2026 года лимит сервисных сообщений сбрасывается ежемесячно для каждого рабочего номера телефона. Неиспользованный остаток не переносится на следующий месяц, а индивидуальные и групповые сервисные сообщения используют общий лимит. После его исчерпания индивидуальные сервисные сообщения тарифицируются по типу regular, если не применяются правила бесплатной точки входа. С этой же даты шаблоны служебных сообщений (utility) в рамках окна обслуживания клиентов больше не являются бесплатными только из-за того, что окно открыто, и не покрываются сервисным лимитом. Сообщения, на которые распространяются правила бесплатной точки входа, продолжают тарифицироваться по типу free_entry_point. Окно бесплатной точки входа открывается, когда пользователь отправляет сообщение компании через рекламу с переходом в WhatsApp или кнопку WhatsApp на Странице Facebook с использованием WhatsApp для Android или iOS, а компания отвечает в течение 24 часов. Окно действует 72 часа с момента ответа компании. Десктопные и веб-клиенты WhatsApp не подпадают под действие этого правила точки входа.

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

Следующие фрагменты обратного вызова представляют собой индивидуальные сообщения. Идентификаторы и суммы списаний приведены для иллюстрации и не являются действующими тарифами. Полные примеры полезной нагрузки см. в разделе WhatsApp Message Updated Webhook Examples.

4.1 Маркетинговое сообщение: платное

Доставленное маркетинговое сообщение использует тарификацию regular. Иллюстративная окончательная сумма составляет 0.05 USD.

{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000001",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "marketing",
    "totalPrice": 0.05,
    "currency": "USD"
  }
}

4.2 Сервисное сообщение: платное

С 1 октября 2026 года, когда рабочий номер телефона исчерпал ежемесячный лимит в 1000 бесплатных сервисных сообщений и сообщение не подпадает под правила бесплатной точки входа, YCloud сообщает о значении pricingType=regular. Иллюстративная окончательная сумма составляет 0.01 USD.

{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000002",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "regular",
    "pricingCategory": "service",
    "totalPrice": 0.01,
    "currency": "USD"
  }
}

4.3 Сервисное сообщение: в пределах бесплатного лимита

Начиная с 1 октября 2026 года для сообщений, входящих в ежемесячный лимит из 1000 бесплатных сервисных сообщений для бизнес-номера, YCloud передает pricingType=free_customer_service и итоговую сумму 0.

{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000003",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_customer_service",
    "pricingCategory": "service",
    "totalPrice": 0,
    "currency": "USD"
  }
}

4.4 Сообщение с бесплатной точки входа (Free-entry point)

Для сообщений, доставленных в течение 72-часового окна бесплатной точки входа, YCloud передает pricingType=free_entry_point, pricingCategory=referral_conversion и итоговую сумму 0.

{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000004",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_entry_point",
    "pricingCategory": "referral_conversion",
    "totalPrice": 0,
    "currency": "USD"
  }
}

Начало работы

Руководства

Конечные точки

Webhooks

Руководство по интеграции тарификации сообщений WhatsApp

1. Событие подписки

2. Поля тарификации

3. Правила тарификации

3.1 Окончательная фиксация цены

3.2 Платные и бесплатные типы тарификации

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

4.1 Маркетинговое сообщение: платное

4.2 Сервисное сообщение: платное

4.3 Сервисное сообщение: в пределах бесплатного лимита

4.4 Сообщение с бесплатной точки входа (Free-entry point)

​1. Событие подписки

​2. Поля тарификации

​3. Правила тарификации

​3.1 Окончательная фиксация цены

​3.2 Платные и бесплатные типы тарификации

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

​4.1 Маркетинговое сообщение: платное

​4.2 Сервисное сообщение: платное

​4.3 Сервисное сообщение: в пределах бесплатного лимита

​4.4 Сообщение с бесплатной точки входа (Free-entry point)

1. Событие подписки

2. Поля тарификации

3. Правила тарификации

3.1 Окончательная фиксация цены

3.2 Платные и бесплатные типы тарификации

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

4.1 Маркетинговое сообщение: платное

4.2 Сервисное сообщение: платное

4.3 Сервисное сообщение: в пределах бесплатного лимита

4.4 Сообщение с бесплатной точки входа (Free-entry point)