---
title: "Управление Retention Messaging через CLI"
description: "Настройте Apple Retention Messaging из терминала с помощью Adapty CLI: подключите realtime URL, запустите тест производительности, создавайте, изменяйте, активируйте и деактивируйте retention-сообщения, просматривайте их метрики."
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

Adapty CLI настраивает [Apple Retention Messaging](retention-messaging) — сообщение, которое подписчики видят на экране **Cancel Subscription** — из терминала, в рамках темы `adapty retention-messaging`. Вы можете узнать статус настройки приложения, подключить Apple к realtime URL Adapty, который отвечает на запросы Apple о сообщении, запустить тест производительности Apple, создавать и изменять retention-сообщения, активировать и деактивировать их, а также просматривать метрики каждого сообщения.

Используйте его, чтобы AI-агент настроил Retention Messaging за вас, создал сообщения для нескольких приложений или считал метрики сообщений без открытия дашборда. Команды выполняют те же действия, что и страница **Retention Messaging** дашборда, и дашборд отображает те же сообщения.

## Перед началом работы \{#before-you-start\}

Топик `retention-messaging` использует ту же установку и авторизацию, что и остальные части CLI. Если вы этого ещё не сделали, выполните шаги 1 и 2 из [гайда по быстрому старту](developer-cli-quickstart). Чтобы проверить, доступен ли этот топик в вашем CLI, выполните:

```bash
adapty retention-messaging --help
```

Каждая команда принимает UUID приложения в параметре `--app`. Чтобы его найти, выполните:

```bash
adapty apps list
```

Что нужно вашему приложению для каждого шага:

- **Читать статус настройки**: Не требуется ничего. Работает для любого приложения.
- **Читать realtime URL**: Полная [настройка App Store](app-store-connection-configuration) в Adapty. Этот URL вы отправляете Apple при запросе доступа.
- **Настроить realtime URL и запустить тест производительности**: Также требуются In-App Purchase key и [доступ к Retention Messaging API](retention-messaging-setup#request-access-from-apple), который вы запрашиваете у Apple. Проверка со стороны Apple может занять до месяца, поэтому запрашивайте доступ заблаговременно.
- **Показывать сообщения подписчикам**: Доступ от Apple, realtime URL, указанный в Adapty, хотя бы один [продукт](create-product) и одобрение Apple для каждого сообщения.

Сообщения Retention Messaging существуют в двух окружениях Apple: `sandbox` и `production`. Флаг `--mode` выбирает окружение. У каждого окружения свои сообщения, что отражает переключатель **Sandbox mode** на дашборде.

Чтобы настроить Retention Messaging с нуля:

1. [Прочитайте статус настройки](#read-the-setup-status).
2. [Прочитайте realtime URL](#connect-the-realtime-url) и запросите доступ у Apple с его помощью.
3. [Настройте realtime URL](#connect-the-realtime-url) для `sandbox`.
4. [Запустите тест производительности](#run-the-performance-test) и читайте статус настройки до тех пор, пока тест не пройдёт.
5. [Настройте realtime URL](#connect-the-realtime-url) для `production`.
6. [Создайте сообщения по умолчанию](#create-a-message), затем промо-сообщения.
7. [Просмотрите список сообщений](#list-and-read-messages), чтобы следить за проверкой Apple.

## Просмотр статуса настройки \{#read-the-setup-status\}

```bash
adapty retention-messaging setup-status --app <app-id>
```

Статус отображает те же шаги настройки, что и дашборд:

| Поле | Значения |
|---|---|
| `credentials` | `present` или `missing`: есть ли у приложения ключи App Store, которые использует Retention Messaging. |
| `registration_status` | `registered` или `not_registered`: предоставил ли Apple приложению доступ к API Retention Messaging. |
| `sandbox.realtime_url_status`, `production.realtime_url_status` | `not_configured`, `configured_to_other_url` или `configured_to_adapty`: куда Apple отправляет запросы в каждой среде. |
| `sandbox.performance_test_status` | `not_started`, `running`, `passed` или `failed`. |

:::note
Некоторые операции чтения также обновляют Adapty, как это делает дашборд:
- Пока выполняется тест производительности, `setup-status` запрашивает у Apple его результат и сохраняет его. `realtime-url configure` выполняет такое же чтение перед запросом подтверждения, поэтому результат сохраняется, даже если вы затем откажетесь.
- `messages list`, `messages get` и чтение, которое `messages update` выполняет перед записью, запрашивают у Apple статус проверки каждого сообщения и сохраняют новое состояние. Если Apple одобрила сообщение, чтение сразу переводит его в статус `live`. Adapty также самостоятельно проверяет статус проверки Apple, так что одобренное сообщение уходит в эфир и без чтения.
:::

## Подключите URL для запросов в реальном времени \{#connect-the-realtime-url\}

Apple отправляет запрос на URL в реальном времени, когда подписчик открывает экран **Cancel Subscription**. Adapty отвечает на этот запрос вашим сообщением. Чтобы узнать URL Adapty, выполните:

```bash
adapty retention-messaging realtime-url get --app <app-id>
```

Один и тот же URL используется для `sandbox` и `production`. Вы передаёте этот URL в Apple при [запросе доступа](retention-messaging-setup#request-access-from-apple).

Чтобы задать URL Adapty в Apple для одной среды, выполните:

```bash
adapty retention-messaging realtime-url configure --app <app-id> --mode sandbox
```

Сначала настройте `sandbox`. Adapty не разрешает использовать `production` до тех пор, пока не будет пройден [тест производительности](#run-the-performance-test). При настройке `sandbox` Adapty также создаёт скрытое тестовое сообщение для теста производительности. Это сообщение не отображается в списке сообщений.

Если Apple отправляет запросы этой среды на другой сервер (`configured_to_other_url`), URL Adapty заменяет URL этого сервера в Apple. После этого тот сервер перестаёт получать запросы с экрана **Cancel Subscription**. CLI выводит предупреждение с указанием среды. Чтобы подтвердить замену:

- **В терминале без `--json`**: Прочитайте предупреждение и ответьте `y` на запрос `Apply? [y/N]`. Запрос появляется даже при передаче `--yes`.
- **В скрипте, агенте или с `--json`**: Передайте `--replace-other-url --yes`. Без `--replace-other-url` CLI ничего не отправляет и завершается с кодом 6, даже при наличии `--yes`.

## Запустите тест производительности \{#run-the-performance-test\}

Apple проверяет скорость ответа Adapty, прежде чем разрешить использование `production` realtime URL. Перед запуском теста [настройте realtime URL](#connect-the-realtime-url) для `sandbox`. Затем совершите покупку продукта с самым длинным сроком действия через sandbox-аккаунт или TestFlight, оставьте подписку активной и запустите тест сразу после покупки:

```bash
adapty retention-messaging performance-test start --app <app-id>
```

Тест всегда выполняется в `sandbox` и может занять до часа. Чтобы увидеть результат, снова прочитайте [статус настройки](#read-the-setup-status): `sandbox.performance_test_status` изменится с `running` на `passed` или `failed`. Пока статус `running`, не запускайте тест повторно — Adapty отклонит запрос. Чтобы разобраться, почему тест не прошёл, см. [Pass the performance test](retention-messaging-setup#pass-the-performance-test).

Когда тест пройдёт, подключите продакшен:

```bash
adapty retention-messaging realtime-url configure --app <app-id> --mode production
```

## Список и просмотр сообщений \{#list-and-read-messages\}

```bash
adapty retention-messaging messages list --app <app-id> --mode production --state live
```

`--mode` обязателен. Список отображает каждое сообщение с его названием, типом, статусом, количеством продуктов, датой начала и следующими метриками за всё время существования сообщения:

| Поле | Столбец в дашборде | Значение |
|---|---|---|
| `shown` | **Shown** | Количество |
| `retained` | **Retained users** | Количество |
| `saved_users` | **Saved users** | Количество |
| `retention_rate` | **Retention rate** | Процент, один знак после запятой. `0.0`, пока ни одно отображение не получило результата. |
| `save_rate` | **Save rate** | Процент, один знак после запятой. `0.0`, пока ни одно отображение не старше 24 часов. |
| `saved_revenue` | **Saved revenue** | USD до вычета комиссии Apple, два знака после запятой |

О том, как Adapty рассчитывает каждую метрику, читайте в разделе [Отслеживание эффективности сообщений](retention-messaging-analytics).

Сообщение может находиться в одном из следующих состояний: `in_review`, `live`, `rejected` или `inactive`. Описание каждого состояния см. в разделе [Состояния сообщений](retention-messaging-create#message-states).

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

```bash
adapty retention-messaging messages get <message-id> --app <app-id>
```

У сообщения нет поля среды. Тексты и пункты списка являются источником на `en-US`. Для каждой другой локали отображается её собственный статус проверки.

## Создание сообщения \{#create-a-message\}

Для промо-сообщения необходим дефолтное сообщение для того же продукта в той же среде. Сначала создайте дефолтное сообщение. Ждать проверки Apple при этом не нужно.

Чтобы найти идентификаторы продуктов, promotional offers и переключения планов для файла, используйте [команды suggest](#find-products-and-offers). Чтобы создать сообщение, поместите его содержимое в JSON-файл:

```json title="message.json"
{
  "name": "Annual default",
  "type": "default",
  "title": "Before you go",
  "body": "Your plan keeps every feature you use today.",
  "alt_text": "App icon on a purple background",
  "header_position": "above_body",
  "products": [
    { "store_id": "com.example.annual" }
  ],
  "bullet_points": [
    { "image_path": "icons/sync.png", "text": "Sync on all your devices" },
    { "image_path": "icons/offline.png", "text": "Work offline" }
  ],
  "localizations": [
    {
      "locale": "de-DE",
      "title": "Bevor du gehst",
      "body": "Dein Abo behält alle Funktionen, die du heute nutzt.",
      "bullet_points": [
        { "text": "Auf allen Geräten synchronisieren" },
        { "text": "Offline arbeiten" }
      ]
    }
  ]
}
```

Then run:

```bash
adapty retention-messaging messages create --app <app-id> --mode sandbox \
  --file message.json --image header.png
```

The file takes these keys:

- **`name`, `type`, `title`, `body`**: Обязательные поля. `title` и `body` — исходный текст на `en-US`, до 66 и 144 символов соответственно.
- **`type`**: Тип сообщения: `default` или `promo`. Изменить тип после создания нельзя.
- **`alt_text`**: Описание изображения для экранных читалок, до 150 символов.
- **`header_position`**: Положение заголовка в сообщении типа `default` с изображением. `above_image` — заголовок над изображением. `above_body` — под изображением, над телом. Изменить после создания нельзя.
- **`products`**: Продукты, подписчики которых видят сообщение, по идентификатору продукта App Store в поле `store_id`. У сообщения типа `default` нет поля `association`. Сообщение типа `promo` требует хотя бы одного продукта, и у каждого продукта должен быть стимул в поле `association`: `{"type": "promo_offer", "store_id": "<offer-id>"}` или `{"type": "plan_switch", "store_id": "<product-id>"}`. Все продукты одного promo-сообщения используют одинаковый тип стимула: либо все `promo_offer`, либо все `plan_switch`.
- **`bullet_points`**: До пяти пунктов, только для сообщений типа `default`. Каждый содержит `text` (1–66 символов), необязательный `alt_text` и `image_path` — путь к PNG-иконке относительно папки JSON-файла. CLI отклоняет `image_index`.
- **`localizations`**: По одной записи для каждой локали, кроме `en-US`, с полями `locale`, `title`, `body` и одним текстом `bullet_points` для каждого пункта сообщения в том же порядке.

`--image` добавляет изображение для сообщения по умолчанию. Промо-сообщение не имеет изображения и маркированных списков.

Перед тем как запросить подтверждение, CLI проверяет каждый файл изображения. Затем CLI запрашивает подтверждение, как описано в [Подтверждение в скриптах и агентах](#confirmation-in-scripts-and-agents). Adapty отправляет тексты и изображения нового сообщения на проверку в Apple, и сообщение переходит в состояние `in_review`.

Если команда создания завершилась с сетевой ошибкой или ошибкой сервера, не запускайте её повторно. См. [Если на создание или изменение нет ответа](#if-a-create-or-a-change-gets-no-answer).

### Требования к изображениям

| Файл | Требования |
|---|---|
| Изображение (`--image`) | PNG, ширина 3840 пикселей, высота 160–2160 пикселей, без прозрачности, до 10 МБ |
| Иконка для буллита (`image_path`) | PNG, 1024 × 1024 пикселей, без прозрачности, до 10 МБ |

CLI проверяет каждый файл перед отправкой. PNG с альфа-каналом пройдёт проверку, если все пиксели полностью непрозрачны. Повреждённый PNG завершится ошибкой `must be a PNG`. Если файл не прошёл проверку, CLI ничего не отправляет и завершает работу с кодом 2. В сообщении об ошибке указывается файл и нарушенное правило, например `… must be 3840 px wide and 160–2160 px tall`.

## Изменить сообщение \{#change-a-message\}

:::warning
Любое изменение неактивного сообщения снова активирует его — даже простое переименование. После одобрения Apple сообщение увидят подписчики.
:::

`messages update` изменяет только то, что вы указываете. Все локали, пункты списка, иконка, продукт и изображение, которые вы не указали, остаются без изменений:

```bash
adapty retention-messaging messages update <message-id> --app <app-id> --title "Wait, there's more"
```

Измените название, заголовок, текст, альтернативный текст и изображение с помощью флагов: `--name`, `--title`, `--body`, `--alt-text`, `--image`, и `--remove-image`. Измените локали, буллет-поинты и продукты с помощью файла изменений, передаваемого через `--file`. Файл изменений также принимает `name`, `title`, `body`, `alt_text` и `remove_image`. CLI отклоняет ключ, который файл изменений не поддерживает. Этот файл изменений работает с сообщением из [Создать сообщение](#create-a-message):

```json title="changes.json"
{
  "localizations": [
    { "locale": "de-DE", "title": "Warte kurz", "bullet_texts": { "<bullet-id>": "Auf jedem Gerät synchronisieren" } }
  ],
  "bullet_points": [
    { "bullet_id": "<bullet-id>", "text": "Sync on every device" },
    {
      "image_path": "icons/backup.png",
      "text": "Daily backups",
      "texts": { "de-DE": "Tägliche Backups" }
    }
  ],
  "remove_bullet_points": ["<other-bullet-id>"]
}
```

- **Локали**: Укажите каждую локаль по её коду в `locale`, с `title`, `body` и текстами буллетов локали в `bullet_texts`, по `bullet_id`. Локаль, которой нет в сообщении, будет добавлена — для неё нужны `title`, `body` и текст для каждого буллета.
- **Буллеты**: Чтобы изменить буллет, укажите его по `bullet_id` из `messages get`, с `text`, `alt_text` или `image_path` для новой иконки. Новый буллет не имеет `bullet_id`. Ему нужны `image_path`, текст `en-US` в `text` и текст в `texts` для каждой локали сообщения.
- **Продукты**: По их App Store product ID в `store_id`. Продукт, которого нет в сообщении, будет добавлен. В промо-сообщении каждый продукт требует стимула: чтобы изменить его, передайте новый `association`. Чтобы прекратить предлагать стимул для продукта, удалите продукт через `remove_products`. Продукт, добавляемый в промо-сообщение, требует `association`.
- **Удаление**: Используйте поля удаления: `remove_localizations` (коды локалей), `remove_bullet_points` (идентификаторы буллетов), `remove_products` (App Store product ID) и `remove_image: true` или `--remove-image`. Удалённый буллет исчезает из всех локалей. Пока промо-сообщение использует продукт, нельзя удалить этот продукт из его основного сообщения.

Вы не можете изменить тип, `header_position` или тип стимула промо-сообщения (`promo_offer` или `plan_switch`). Чтобы использовать другой вариант, создайте новое сообщение.

CLI проверяет ваши изменения перед отправкой. Если входные данные противоречат сами себе, ничего не меняют или указывают на то, чего в сообщении нет, либо удаляют несуществующее, CLI ничего не отправляет, завершает работу с кодом 2, а ошибка указывает на проблему. Локализованные тексты существующего пункта маркированного списка нужно указывать в `bullet_texts` соответствующей локали, а не в `texts`.

CLI запрашивает подтверждение, считывает сообщение, объединяет ваши изменения и отправляет полное сообщение в Adapty. При каждом обновлении всё сообщение отправляется на проверку в Apple, и статус сообщения меняется на `in_review`. Если кто-то изменит сообщение в дашборде во время выполнения `messages update`, обновление перезапишет эти изменения.

## Активация и деактивация сообщения \{#activate-or-deactivate-a-message\}

```bash
adapty retention-messaging messages set-status <message-id> --app <app-id> --action deactivate
```

- **`activate`**: Переводит сообщение из статуса `inactive` в `in_review`. Apple повторно проверяет только те локали, которые ещё не были одобрены. После одобрения подписчики снова начинают видеть сообщение.
- **`deactivate`**: Переводит сообщение из статуса `live` в `inactive`. Подписчики перестают его видеть. Уже накопленные показы остаются в метриках.

Adapty отклоняет `activate` для сообщения, которое не находится в состоянии `inactive`, и `deactivate` для сообщения, которое не находится в состоянии `live`. Сообщение в состоянии `in_review` переходит в статус live после одобрения Apple. Чтобы остановить его, деактивируйте после этого. В CLI нет команды для удаления сообщения.

У продукта может быть одно стандартное сообщение и одно промо-сообщение в каждой среде. Adapty отклоняет активацию в следующих случаях:

- Пока это сообщение было неактивным, к продукту было добавлено другое сообщение того же типа.
- Сообщение является промо-сообщением, и у одного из его продуктов нет стандартного сообщения в данной среде.

Пока промо-сообщение использует продукт, Adapty не позволяет деактивировать сообщение по умолчанию для этого продукта. Сначала деактивируйте промо-сообщение или удалите из него продукт.

## Найти продукты и офферы \{#find-products-and-offers\}

Чтобы найти продукты, которые можно добавить в сообщение, выполните:

```bash
adapty retention-messaging products suggest --app <app-id> --mode production --type default
```

При изменении сообщения передайте его ID в `--message-id`, чтобы продукты этого сообщения не отображались как `used`. Продукт с `disabled_reason` добавить нельзя:

- **`used`**: Другое сообщение того же типа в этом окружении уже использует этот продукт.
- **`no_default_message`**: У продукта нет дефолтного сообщения в этом окружении, поэтому он не может получить промо-сообщение.

Промо-сообщение связывает одно поощрение с каждым продуктом. Чтобы найти поощрения для продукта, передайте `id` продукта из `products suggest`. Чтобы получить список promotional offers продукта, выполните:

```bash
adapty retention-messaging promo-offers suggest <product-id> --app <app-id>
```

Чтобы получить список планов, на которые подписчик может перейти, выполните:

```bash
adapty retention-messaging plan-switches suggest <product-id> --app <app-id>
```

`plan-switches suggest` требует [ключ App Store Connect API](app-store-connect-api-key) в настройках приложения. Укажите `store_id` предложения или плана в поле `association` продукта.

## Подтверждение в скриптах и агентах \{#confirmation-in-scripts-and-agents\}

Эти команды влияют на то, что подписчики видят на экране **Cancel Subscription**. Каждая из них выводит описание изменения и запрашивает подтверждение перед отправкой — в `sandbox` и в `production`:

- `realtime-url configure`
- `messages create`
- `messages update`
- `messages set-status`

Способ запроса зависит от того, как запускается команда:

| Способ запуска команды | Что происходит |
|---|---|
| В терминале, без `--yes` и без `--json` | CLI выводит информацию об операции и спрашивает `Apply? [y/N]`. Если вы ответите `y` или `yes`, CLI отправит запрос. При любом другом ответе CLI завершится с кодом 1 и ничего не отправит. |
| С `--yes`, в терминале или без него | CLI отправляет запрос без подтверждения, даже в `production`. |
| Без `--yes`, с `--json`, в пайпе или без терминала | CLI ничего не отправляет и завершается с кодом 6. Ошибка описывает выполняемую операцию. |

Замена другого URL-адреса реального времени в Apple имеет свои правила. См. [Подключение URL-адреса реального времени](#connect-the-realtime-url).

Таким образом, скрипт или агент могут сначала посмотреть, что сделает команда: запустить её без `--yes`, прочитать результат в выводе и повторно запустить с `--yes` только после того, как кто-то подтвердит это действие.

`setup-status`, `realtime-url get`, `performance-test start`, `messages list`, `messages get` и команды `suggest` выполняются без запроса подтверждения.

## Ошибки \{#errors\}

| Код выхода | Причина | Что делать |
|---|---|---|
| 1 | На запрос вы ответили что-то, кроме `y`. Ничего не отправлено. | Запустите команду снова, если хотели продолжить. |
| 2 | CLI отклонил ввод до отправки изменения: неверный флаг, файл изображения, конфликт во вводе, локаль без текста для каждого пункта или удаление того, чего нет в retention-сообщении. | Исправьте то, что указано в ошибке. |
| 3 | Вы не вошли в систему, или Adapty отказал в доступе к приложению. | Войдите с помощью `adapty auth login` и найдите идентификатор приложения в `adapty apps list`. |
| 4 | Adapty отклонил запрос. Ошибка содержит причину, а `--json` возвращает HTTP-статус и `error_code`. Серверная ошибка (5xx) при создании или изменении также даёт код 4, а результат операции неизвестен. | См. [Сообщения от Adapty](#messages-from-adapty). После серверной ошибки при создании или изменении см. [Если на создание или изменение не пришёл ответ](#if-a-create-or-a-change-gets-no-answer). |
| 5 | CLI не смог подключиться к Adapty. | Убедитесь, что вы онлайн. После создания или изменения см. [Если на создание или изменение не пришёл ответ](#if-a-create-or-a-change-gets-no-answer). |
| 6 | Команда, требующая подтверждения, была запущена без `--yes` и без возможности ответить, или замена URL в реальном времени запущена без `--replace-other-url`. Ничего не отправлено. | Прочитайте описание эффекта в ошибке, затем запустите команду снова с `--yes`, а для замены — с `--replace-other-url`. |
| 130 | Вы нажали Ctrl+C на запросе. Ничего не отправлено. | — |

### Сообщения от Adapty

С флагом `--json` ошибка возвращает `error_code`:

| `error_code` | Причина | Что делать |
|---|---|---|
| `app_store_credentials_missing` | В приложении не настроены ключи App Store в Adapty. | Выполните [настройку App Store](app-store-connection-configuration). |
| `app_store_connect_credentials_missing` | Команде `plan-switches suggest` требуется ключ App Store Connect API. | Добавьте [ключ App Store Connect API](app-store-connect-api-key). |
| `realtime_url_unavailable` | В приложении не настроены серверные уведомления App Store в Adapty. | Выполните [настройку App Store](app-store-connection-configuration). |
| `apple_rm_api_access_denied` | Apple не предоставила приложению доступ к Retention Messaging API. | [Запросите доступ у Apple](retention-messaging-setup#request-access-from-apple). |
| `performance_test_required` | Вы настроили `production` до прохождения теста производительности. | Сначала [запустите тест производительности](#run-the-performance-test). |
| `performance_test_already_running` | Тест производительности уже выполняется. | Подождите и снова проверьте статус настройки. |
| `active_sandbox_transaction_missing` | Нет активной подписки в песочнице. | Приобретите продукт с максимальным сроком действия в песочнице, затем начните тест заново. |
| `performance_test_request_rejected` | Apple отклонила запрос на запуск теста. | Совершите новую покупку в песочнице, затем начните тест заново. |
| `retention_product_claimed` | Другое сообщение того же типа уже использует этот продукт. | Выберите другой продукт или деактивируйте другое сообщение. |
| `retention_default_message_missing` | У промо-сообщения есть продукт без дефолтного сообщения. | Сначала создайте или активируйте дефолтное сообщение для продукта. |
| `retention_dependent_promo_messages` | Промо-сообщение использует продукт, который изменение отнимает у дефолтного сообщения. | Сначала деактивируйте промо-сообщение или удалите из него продукт. |
| `retention_promo_association_invalid` | У промо-сообщения нет продукта, у продукта нет `association`, или используются оба типа стимулов. | Задайте каждому продукту `association` одного типа. |
| `retention_message_type_immutable` | Изменение присваивает промо-сообщению другой тип стимула. | Создайте новое сообщение. |
| `retention_message_invalid_status_transition` | Команда `activate` применяется к сообщению не в статусе `inactive`, или `deactivate` — к сообщению не в статусе `live`. | Узнайте состояние сообщения с помощью `messages get`. |
| `retention_message_not_found` | В приложении нет сообщения с таким ID. | Возьмите ID из `messages list`. |

### Если на запрос создания или изменения нет ответа \{#if-a-create-or-a-change-gets-no-answer\}

Если CLI не получает ответа на запрос создания или обновления из-за сетевой ошибки или ошибки сервера (код выхода 4 или 5), он не может определить, сохранил ли Adapty изменение. CLI не отправляет запрос повторно. Не запускайте команду снова самостоятельно.

- **После create**: Выполните `messages list` для того же окружения с `--search "<name>" --page-size 100`. В случае ошибки точное имя выводится на отдельной строке (`message_name` в `--json`). Читайте все страницы до `meta.pagination.pages` и открывайте каждого кандидата через `messages get`. Повторный create может создать дублирующееся сообщение и отправить его на проверку Apple. Создавайте сообщение заново только если ни один кандидат не является вашим сообщением.
- **После update**: Выполните `messages get` и проверьте статус и содержимое сообщения.

## Справочник команд \{#command-reference\}

Каждая команда принимает `--app` — UUID приложения из `adapty apps list`.

### `retention-messaging setup-status`

Возвращает статус настройки. Не принимает других флагов.

### `retention-messaging realtime-url get`

Возвращает realtime URL Adapty. Не принимает дополнительных флагов.

### `retention-messaging realtime-url configure`

| Flag | Обязательный | Описание |
|---|---|---|
| `--mode` | Да | `sandbox` или `production`. |
| `--replace-other-url` | Нет | Подтвердить замену другого URL в Apple. |
| `--yes`, `-y` | Нет | Настроить без запроса подтверждения. Обязательно при использовании `--json` или в пайпе. |

### `retention-messaging performance-test start`

Запускает performance-тест Apple в `sandbox`. Не принимает других флагов.

### `retention-messaging messages list`

| Флаг | Обязательный | Описание |
|---|---|---|
| `--mode` | Да | `sandbox` или `production`. |
| `--search` | Нет | Часть названия в любом регистре или точный ID сообщения. |
| `--type` | Нет | `default` или `promo`. |
| `--state` | Нет | `in_review`, `live`, `rejected` или `inactive`. |
| `--ordering` | Нет | `name`, `type`, `state`, `products_count` или `started_at`. Добавьте `-` перед полем для обратного порядка. По умолчанию: `-started_at`. |
| `--page` | Нет | Номер страницы. По умолчанию: 1. |
| `--page-size` | Нет | Сообщений на странице, не более 100. По умолчанию: 20. |

### `retention-messaging messages get`

Принимает идентификатор сообщения в качестве аргумента. Возвращает полное сообщение.

### `retention-messaging messages create`

| Флаг | Обязательный | Описание |
|---|---|---|
| `--mode` | Да | `sandbox` или `production`. |
| `--file` | Да | JSON-файл сообщения или `-` для чтения из стандартного ввода. См. [Создание сообщения](#create-a-message). |
| `--image` | Нет | PNG-изображение сообщения по умолчанию. |
| `--yes`, `-y` | Нет | Создать без подтверждения. Обязателен при использовании `--json` или в пайпе. |

### `retention-messaging messages update`

Принимает ID сообщения в качестве аргумента.

| Флаг | Обязательный | Описание |
|---|---|---|
| `--name`, `--title`, `--body`, `--alt-text` | Нет | Новое значение поля. |
| `--image` | Нет | Новое PNG-изображение. |
| `--remove-image` | Нет | Удалить изображение. |
| `--file` | Нет | Файл с изменениями или `-` для чтения из стандартного ввода. См. [Изменение сообщения](#change-a-message). |
| `--yes`, `-y` | Нет | Изменить без подтверждения. Обязателен при использовании `--json` или в пайпе. |

### `retention-messaging messages set-status`

Принимает ID сообщения в качестве аргумента.

| Флаг | Обязательный | Описание |
|---|---|---|
| `--action` | Да | `activate` или `deactivate`. |
| `--yes`, `-y` | Нет | Изменить статус без подтверждения. Обязателен при использовании `--json` или в пайпе. |

### `retention-messaging products suggest`

| Flag | Required | Description |
|---|---|---|
| `--mode` | Yes | `sandbox` или `production`. |
| `--type` | Yes | `default` или `promo`: тип сообщения. |
| `--search` | No | Часть названия продукта, любой регистр. |
| `--message-id` | No | ID сообщения, которое вы изменяете. |
| `--limit` | No | Количество возвращаемых продуктов, до 100. По умолчанию: 10. |

### `retention-messaging promo-offers suggest`

Принимает ID продукта из `products suggest` в качестве аргумента.

| Флаг | Обязательный | Описание |
|---|---|---|
| `--search` | Нет | Часть названия предложения, любой регистр. |
| `--limit` | Нет | Количество возвращаемых предложений, до 100. По умолчанию: 10. |

### `retention-messaging plan-switches suggest`

Принимает ID продукта из `products suggest` в качестве аргумента.

| Флаг | Обязательный | Описание |
|---|---|---|
| `--search` | Нет | Часть названия плана, в любом регистре. |
| `--limit` | Нет | Количество возвращаемых планов, до 100. По умолчанию: 10. |

## Работа с AI-ассистентом \{#work-from-an-ai-assistant\}

[MCP-сервер Adapty](adapty-mcp) предоставляет те же действия, что и инструменты `retention_messaging_*`, например `retention_messaging_messages_list` для `messages list`. Инструменты принимают `message_type` вместо `--type`.

- **Подтверждение**: Ассистент спрашивает разрешение перед настройкой realtime URL, созданием или изменением сообщения, а также перед изменением статуса — как в `sandbox`, так и в `production`. Перед заменой realtime URL другого сервера задаётся отдельный вопрос. Кроме того, один раз за сессию ассистент спрашивает перед первым чтением статуса настройки и один раз перед первым чтением сообщения, поскольку [эти операции могут обновить данные в Adapty](#read-the-setup-status).
- **Изображения и маркеры списка**: Инструменты MCP не поддерживают добавление изображений, иконок маркеров и новых пунктов списка. `retention_messaging_messages_create` создаёт сообщение без изображений и маркеров. Чтобы добавить их, используйте команду `messages update` в CLI или дашборд.

## Что дальше \{#whats-next\}

- [Скилл агента для Retention Messaging](retention-messaging-skill) — пусть агент настроит Retention Messaging и напишет сообщения, с вашим подтверждением перед каждым изменением.
- [Настройка Retention Messaging](retention-messaging-setup) — те же шаги настройки в дашборде.
- [Создание retention-сообщения](retention-messaging-create) — поля сообщения, локали и статусы в дашборде.
- [Отслеживание эффективности сообщений](retention-messaging-analytics) — что означает каждая метрика.