# Интеграция с центром уведомлений через модуль «Уведомления и мессенджеры»

Если в вашем мобильном приложении или личном кабинете есть центр уведомлений (ЦУ), Mindbox может отправлять в него рассылки из модуля «Уведомления и мессенджеры». Маркетолог создает рассылку в канале «Центр уведомлений», Mindbox передает сообщение на ваш сервер, а ваш сервер возвращает в Mindbox открытия, клики и недоставки — они попадают в статистику рассылки.

:::note

Эта интеграция не требует SDK Mindbox. Если ЦУ должен хранить мобильные пуши, отправленные через SDK, используйте инструкцию [Центр уведомлений](/docs/notification-center).

:::

## Перед началом

Убедитесь, что:

* Подключен модуль Mindbox «Уведомления и мессенджеры» в разделе **Подписка и оплата** — [подробнее](https://help.mindbox.ru/docs/billing-modules#vklyuchit-i-vyklyuchit-modul).
* Ваш сервер доступен из интернета по HTTPS. Mindbox и ваш сервер обмениваются запросами только по HTTPS.

## Шаг 1. Создайте endpoint для приема сообщений

Endpoint для приема сообщений создаете вы: Mindbox не генерирует этот адрес. Endpoint должен принимать POST-запросы и быть доступен из интернета. Путь и логику обработки выберите сами. Адрес endpoint указывается в соединении в поле «Адрес доступа», об этом — в шаге 2.

Mindbox отправляет каждое сообщение отдельным POST-запросом со скоростью до 750 сообщений в секунду.

:::warning

Не меняйте формат приема сообщений и отправки событий без согласования с Mindbox. Если формат изменится только с одной стороны, отправка рассылок и сбор статистики остановятся.

:::

### Заголовки запроса

| Заголовок | Значение |
|---|---|
| `Content-Type` | `application/json; charset=utf-8` |
| `Authorization` | `Basic` и строка Base64 из логина и пароля, указанных в соединении |

### Как проверить, что запрос пришел от Mindbox

Mindbox авторизуется на вашем сервере по схеме Basic: в каждом запросе приходит заголовок `Authorization: Basic <base64(логин:пароль)>`. Раскодируйте этот заголовок и сверьте логин и пароль с теми, что указали в соединении. Так вы убедитесь, что запрос пришел от Mindbox, а не от постороннего.

Чтобы проверить запрос:

1. Возьмите значение заголовка `Authorization`.
2. Уберите префикс `Basic`.
3. Декодируйте оставшуюся строку из Base64 — получится строка вида `логин:пароль`.
4. Сравните логин и пароль с указанными в соединении.

Пример:

```text
Authorization: Basic YWRtaW46NjQ2YmVmYzktZTRhMC00NTgyLTlkN2ItMTY3OGUzZThjNmQw
```

После декодирования:

```text
admin:646befc9-e4a0-4582-9d7b-1678e3e8c6d0
```

Здесь `admin` — логин, `646befc9-e4a0-4582-9d7b-1678e3e8c6d0` — пароль.

### Тело запроса

```json
{
  "messageId": "some_message_id_123",
  "clientId1": "user_12345",
  "clientId2": "79001234567",
  "campaignId": "promo",
  "title": "Заголовок",
  "text": "Это текст уведомления",
  "image": "https://example.com/image.png",
  "link": "https://example.com/promo",
  "buttons": [
    {
      "text": "Кнопка",
      "url": "https://example.com/new"
    }
  ],
  "payload": {
    "param1": "additionalData1",
    "param2": "additionalData2"
  }
}
```

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `messageId` | string | Да | Уникальный идентификатор сообщения, который присваивает Mindbox. Передавайте его в событиях, чтобы Mindbox связал событие с сообщением |
| `clientId1` | string | Нет | Идентификатор пользователя в вашем приложении. Mindbox берет значение из поля карточки клиента, выбранного в соединении в поле «Идентификатор клиента 1» |
| `clientId2` | string | Нет | Второй идентификатор пользователя. Mindbox берет значение из поля карточки клиента, выбранного в соединении в поле «Идентификатор клиента 2» |
| `campaignId` | string | Нет | Значение, которое можно использовать в логике приложения, например чтобы определить раздел ЦУ |
| `title` | string | Нет | Заголовок уведомления |
| `text` | string | Нет | Текст уведомления |
| `image` | string | Нет | Ссылка на изображение |
| `link` | string | Нет | Ссылка на раздел сайта или приложения |
| `buttons` | array | Нет | Кнопки уведомления |
| `buttons[].text` | string | Нет | Текст кнопки |
| `buttons[].url` | string | Нет | Ссылка кнопки |
| `payload` | object | Нет | Дополнительные данные: пары «ключ — значение», значения — строки. Пары задают при настройке рассылки |

Mindbox отправляет сообщение, только если у клиента заполнен хотя бы один из идентификаторов: `clientId1` или `clientId2`. Определяйте по ним получателя на стороне приложения.

### Ответ на запрос

| Код ответа | Значение |
| --- | --- |
| `200` | Сообщение успешно отправлено |
| `401` | Недоставка с причиной «Ошибка аутентификации» |
| `400`, `404`, `409` | Недоставка. Тело ответа выводится в технических подробностях статуса |
| `429`, `500`, `502`, `503`, `504` | Временная недоступность сервера. Mindbox повторяет отправку |

## Шаг 2. Передайте данные для настройки соединения

Соединение «Центр уведомлений» создается в Mindbox в разделе **Настройки** → **Рассылки** → **Соединения**.

Для настройки понадобится:

* Адрес endpoint из шага 1 — для поля «Адрес доступа»;
* Логин и пароль, с которыми Mindbox будет обращаться к endpoint;
* Название поля профиля клиента в Mindbox, в котором хранится идентификатор пользователя вашего приложения, — для полей «Идентификатор клиента 1» и «Идентификатор клиента 2».
  
  :::info

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

  :::

Если у вас несколько брендов или приложений, для каждого нужно отдельное соединение — подготовьте данные для каждого.

![Настройки соединения «Центр уведомлений»](/images/notification-center-integration-connection.png)

## Шаг 3. Отправляйте события в Mindbox

После сохранения соединения скопируйте URL из блока «Открытия и клики по рассылке». Это `callback_url` — на него ваш сервер будет отправлять POST-запросы с событиями.

![Блок «Открытия и клики по рассылке» с URL для отправки событий](/images/notification-center-integration-callback-url.png)

Mindbox принимает три типа событий: открытие, недоставку и клик.

:::warning

Как собирать события в приложении и передавать их на сервер, зависит от архитектуры вашего приложения. Mindbox задает только формат запроса на `callback_url`.

:::

### Заголовки запроса

| Заголовок | Значение |
|---|---|
| `Content-Type` | `application/json; charset=utf-8` — всегда |
| `Authorization` | Зависит от настроек интеграции: Basic, Bearer, API-ключ в отдельном заголовке или токен в теле запроса |
| Дополнительные заголовки | Например, `Accept: application/json` |

Если Mindbox принял событие, он возвращает `200 OK`.

### Тело запроса

| Параметр | Тип | Описание |
|---|---|---|
| `messageId` | string | Идентификатор сообщения из запроса Mindbox |
| `status` | string | Тип события: `opened` — открытие, `failed` — недоставка, `clicked` — клик |
| `time` | string | Время события в формате ISO 8601 в UTC |
| `status_code` | string | Код ошибки. Только для `failed`, выводится в технических подробностях статуса |
| `description` | string | Описание ошибки. Только для `failed`, выводится в технических подробностях статуса |
| `buttonText` | string | Текст кнопки. Только для клика по кнопке без ссылки |
| `url` | string | Ссылка, по которой кликнул пользователь. Только для клика по ссылке |

### Открытие

```json
{
  "messageId": "some_message_id_123",
  "status": "opened",
  "time": "2025-03-13T13:44:39Z"
}
```

### Недоставка

```json
{
  "messageId": "some_message_id_123",
  "status": "failed",
  "status_code": "status_code",
  "description": "Error description",
  "time": "2025-03-13T13:44:39Z"
}
```

### Клик по кнопке без ссылки

```json
{
  "messageId": "some_message_id_123",
  "status": "clicked",
  "buttonText": "Click here",
  "time": "2025-03-13T13:44:39Z"
}
```

Mindbox записывает клик со ссылкой вида `https://mbxs.ru/button/<текст кнопки>`, например `https://mbxs.ru/button/Click here`.

### Клик по ссылке

Отправляйте это событие, если ссылка не отслеживается кликтрекингом Mindbox и клики считает ваше приложение.

```json
{
  "messageId": "some_message_id_123",
  "status": "clicked",
  "url": "https://some-click-url.com",
  "time": "2025-03-13T13:44:39Z"
}
```

Mindbox записывает клик с переданной ссылкой.

## Проверка результата

1. Попросите маркетолога отправить рассылку в канале «Центр уведомлений» на тестового клиента, у которого заполнено поле с идентификатором пользователя.
2. Проверьте, что endpoint получил запрос и ответил `200`, а сообщение появилось в ЦУ.
3. Откройте сообщение в ЦУ и нажмите кнопку в нем.
4. Попросите маркетолога проверить, что открытие и клик появились в [статусах рассылки](https://help.mindbox.ru/docs/customer-message-statuses) у тестового клиента.

:::warning

Рассылка в канал «Центр уведомлений» не дублируется автоматически как push-уведомление. Для этого необходимо создать две идентичные рассылки для двух каналов: «Центр уведомлений» и «Мобильный пуш».

:::

## Что дальше

* [Центр уведомлений на основе мобильных пушей](/docs/notification-center) — если ЦУ должен хранить пуши, отправленные через SDK Mindbox.
* [Модуль «Уведомления и мессенджеры»](https://help.mindbox.ru/docs/notifications-and-messangers) — какие еще каналы доступны в модуле.