> ## 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.

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

> Узнайте о полях тарификации сообщений WhatsApp, правилах списания и окончательной фиксации цен в вебхуках YCloud.

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

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

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

YCloud отправляет обновления статуса и стоимости сообщений через событие `whatsapp.message.updated`. Подписки доступны в разделе **Developers → Webhook** в консоли YCloud.

Следующий запрос создает подписку через API. Справочную информацию о конечной точке см. в разделе [Create a webhook endpoint](/api-reference/webhook-endpoints/create-a-webhook-endpoint):

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://api.ycloud.com/v2/webhookEndpoints
Content-Type: application/json
X-API-Key: YOUR_YCLOUD_API_KEY
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": ["whatsapp.message.updated"],
  "status": "active"
}
```

`url` указывает конечную точку получения вебхука. Обработка событий и проверка подписи описаны в [Webhook Integration Guide](/ru/api-reference/guides/api-fundamentals/configure-webhooks).

## 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](/api-reference/whatsapp-messages/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](/ru/documentation/pricing-and-billing/whatsapp-pricing-and-billing), вступающим в силу 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](/ru/api-reference/guides/examples/webhook-examples/whatsapp-message-updated-webhook-examples).

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

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "whatsapp.message.updated",
  "whatsappMessage": {
    "id": "66eb00000000000000000004",
    "status": "delivered",
    "pricingModel": "PMP",
    "pricingType": "free_entry_point",
    "pricingCategory": "referral_conversion",
    "totalPrice": 0,
    "currency": "USD"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.