---
title: "Gérer les messages de rétention depuis la CLI"
description: "Configurez les messages de rétention Apple depuis le terminal avec la CLI Adapty : connectez l'URL en temps réel, lancez le test de performance, créez, modifiez, activez et désactivez les messages de rétention, et consultez leurs métriques."
---

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

L'Adapty CLI configure [Apple Retention Messaging](retention-messaging), le message que les abonnés voient sur l'écran **Cancel Subscription**, depuis le terminal, sous la rubrique `adapty retention-messaging`. Vous pouvez lire le statut de configuration d'une app, connecter Apple à l'URL en temps réel d'Adapty qui répond aux requêtes d'Apple pour un message, lancer le test de performance d'Apple, créer et modifier des messages de rétention, les activer et les désactiver, et consulter les métriques de chaque message.

Utilisez-le pour laisser un agent IA configurer Retention Messaging pour vous, créer des messages sur plusieurs applications ou consulter les métriques des messages sans ouvrir le tableau de bord. Les commandes effectuent les mêmes actions que la page **Retention Messaging** du tableau de bord, et le tableau de bord affiche les mêmes messages.

## Avant de commencer \{#before-you-start\}

Le topic `retention-messaging` utilise la même installation et la même connexion que le reste de la CLI. Si vous n'avez pas encore effectué cette configuration, suivez les étapes 1 et 2 du [guide de démarrage rapide](developer-cli-quickstart). Pour vérifier si votre CLI dispose du topic, exécutez :

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

Chaque commande prend l'UUID de l'application dans `--app`. Pour le trouver, exécutez :

```bash
adapty apps list
```

Ce dont votre application a besoin pour chaque étape :

- **Lire le statut de configuration** : Aucun prérequis. Fonctionne avec n'importe quelle application.
- **Lire l'URL en temps réel** : Une [configuration App Store](app-store-connection-configuration) complète dans Adapty. Vous envoyez cette URL à Apple lors de votre demande d'accès.
- **Configurer l'URL en temps réel et exécuter le test de performance** : La clé d'achat intégré, et l'[accès à l'API Retention Messaging](retention-messaging-setup#request-access-from-apple), que vous demandez à Apple. L'examen par Apple peut prendre jusqu'à un mois, donc faites la demande tôt.
- **Afficher les messages aux abonnés** : L'accès d'Apple, l'URL en temps réel configurée dans Adapty, au moins un [produit](create-product), et l'approbation de chaque message par Apple.

Les messages de rétention existent dans deux environnements Apple : `sandbox` et `production`. L'indicateur `--mode` sélectionne l'environnement. Chaque environnement possède ses propres messages, comme le montre la bascule **Sandbox mode** du tableau de bord.

Pour configurer la messagerie de rétention de A à Z :

1. [Lire le statut de configuration](#read-the-setup-status).
2. [Lire l'URL en temps réel](#connect-the-realtime-url), et demander l'accès à Apple avec celle-ci.
3. [Configurer l'URL en temps réel](#connect-the-realtime-url) pour `sandbox`.
4. [Exécuter le test de performance](#run-the-performance-test), et lire le statut de configuration jusqu'à ce que le test soit passé.
5. [Configurer l'URL en temps réel](#connect-the-realtime-url) pour `production`.
6. [Créer les messages par défaut](#create-a-message), puis les messages promotionnels.
7. [Lister les messages](#list-and-read-messages) pour suivre la revue d'Apple.

## Lire le statut de configuration \{#read-the-setup-status\}

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

Le statut affiche les mêmes étapes de configuration que le tableau de bord :

| Champ | Valeurs |
|---|---|
| `credentials` | `present` ou `missing` : indique si l'application dispose des clés App Store utilisées par Retention Messaging. |
| `registration_status` | `registered` ou `not_registered` : indique si Apple a accordé à l'application l'accès à l'API Retention Messaging. |
| `sandbox.realtime_url_status`, `production.realtime_url_status` | `not_configured`, `configured_to_other_url` ou `configured_to_adapty` : destination des requêtes Apple dans chaque environnement. |
| `sandbox.performance_test_status` | `not_started`, `running`, `passed` ou `failed`. |

:::note
Certaines lectures mettent également à jour Adapty, comme le fait le tableau de bord :
- Pendant l'exécution du test de performance, `setup-status` demande à Apple le résultat du test et le sauvegarde. `realtime-url configure` effectue la même lecture avant de demander une confirmation, donc le résultat est sauvegardé même si vous refusez ensuite.
- `messages list`, `messages get`, et la lecture effectuée par `messages update` avant d'écrire demandent à Apple l'état de révision de chaque message et sauvegardent le nouvel état. Si Apple a approuvé un message, la lecture le fait passer immédiatement à `live`. Adapty vérifie également la révision Apple de son côté, donc un message approuvé passe en live sans lecture non plus.
:::

## Connecter l'URL en temps réel \{#connect-the-realtime-url\}

Apple envoie une requête à une URL en temps réel lorsqu'un abonné ouvre l'écran **Cancel Subscription**. Adapty répond à cette requête avec votre message. Pour lire l'URL Adapty, exécutez :

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

La même URL sert à la fois pour `sandbox` et la production. Vous transmettez cette URL à Apple lorsque vous [demandez l'accès](retention-messaging-setup#request-access-from-apple).

Pour définir l'URL Adapty dans Apple pour un environnement, exécutez :

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

Configurez d'abord `sandbox`. Adapty refuse `production` tant que le [test de performance](#run-the-performance-test) n'est pas réussi. Lorsque vous configurez `sandbox`, Adapty crée également un message de test masqué pour le test de performance. Ce message n'apparaît pas dans la liste des messages.

Si Apple envoie les requêtes de cet environnement vers un autre serveur (`configured_to_other_url`), l'URL Adapty remplace l'URL de ce serveur dans Apple. Dès lors, ce serveur ne reçoit plus aucune requête depuis l'écran **Cancel Subscription**. Le CLI affiche un avertissement indiquant le nom de l'environnement. Pour approuver le remplacement :

- **Dans un terminal, sans `--json`** : Lisez l'avertissement et répondez `y` à l'invite `Apply? [y/N]`. L'invite apparaît même si vous passez `--yes`.
- **Dans un script, un agent, ou avec `--json`** : Passez `--replace-other-url --yes`. Sans `--replace-other-url`, le CLI n'envoie rien et quitte avec le code 6, même avec `--yes`.

## Exécuter le test de performance \{#run-the-performance-test\}

Apple teste la vitesse de réponse d'Adapty avant d'autoriser l'URL temps réel en `production`. Avant de lancer le test, [configurez l'URL temps réel](#connect-the-realtime-url) pour `sandbox`. Ensuite, achetez votre produit de la plus longue durée avec un compte sandbox ou via TestFlight, maintenez l'abonnement actif, et démarrez le test juste après l'achat :

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

Le test s'exécute toujours en `sandbox` et peut prendre jusqu'à une heure. Pour voir le résultat, relisez le [statut de configuration](#read-the-setup-status) : `sandbox.performance_test_status` passe de `running` à `passed` ou `failed`. Tant que le statut est `running`, ne relancez pas le test : Adapty le refusera. Pour comprendre pourquoi un test échoue, consultez [Réussir le test de performance](retention-messaging-setup#pass-the-performance-test).

Une fois le test réussi, connectez la production :

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

## Lister et lire les messages \{#list-and-read-messages\}

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

`--mode` est obligatoire. La liste affiche chaque message avec son nom, son type, son état, le nombre de produits, la date de début, ainsi que ces métriques sur toute la durée de vie du message :

| Champ | Colonne du tableau de bord | Valeur |
|---|---|---|
| `shown` | **Shown** | Nombre |
| `retained` | **Retained users** | Nombre |
| `saved_users` | **Saved users** | Nombre |
| `retention_rate` | **Retention rate** | Pourcentage, une décimale. `0.0` tant qu'aucune vue n'a de résultat. |
| `save_rate` | **Save rate** | Pourcentage, une décimale. `0.0` tant qu'aucune vue n'a plus de 24 heures. |
| `saved_revenue` | **Saved revenue** | USD avant commission Apple, deux décimales |

Pour savoir comment Adapty calcule chaque métrique, consultez [Suivre les performances des messages](retention-messaging-analytics).

Un message peut être dans l'un des états suivants : `in_review`, `live`, `rejected` ou `inactive`. Pour connaître la signification de chaque état, consultez [États des messages](retention-messaging-create#message-states).

Pour lire un message avec ses textes, son image, ses puces, ses produits et ses locales, exécutez :

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

Le message ne possède pas de champ d'environnement. Ses textes et ses puces correspondent à la source `en-US`. Chaque autre locale affiche son propre état de révision.

## Créer un message \{#create-a-message\}

Un message promo nécessite un message par défaut pour le même produit dans le même environnement. Créez d'abord le message par défaut. Vous n'avez pas à attendre la validation d'Apple.

Pour trouver les identifiants de produit, les offres promo et les changements de plan à inclure dans le fichier, utilisez les [commandes suggest](#find-products-and-offers). Pour créer un message, placez son contenu dans un fichier 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`** : Obligatoires. Le titre et le corps sont la source `en-US`, jusqu'à 66 et 144 caractères.
- **`type`** : Le type de message, `default` ou `promo`. Vous ne pouvez pas modifier le type ultérieurement.
- **`alt_text`** : La description de l'image pour les lecteurs d'écran, jusqu'à 150 caractères.
- **`header_position`** : La position du titre dans un message par défaut avec une image. `above_image` affiche le titre au-dessus de l'image. `above_body` l'affiche sous l'image, au-dessus du corps. Vous ne pouvez pas le modifier ultérieurement.
- **`products`** : Les produits dont les abonnés voient le message, identifiés par leur ID de produit App Store dans `store_id`. Un message par défaut n'a pas d'`association`. Un message promo nécessite au moins un produit, et chaque produit a besoin d'une incitation dans `association` : `{"type": "promo_offer", "store_id": "<offer-id>"}` ou `{"type": "plan_switch", "store_id": "<product-id>"}`. Tous les produits d'un même message promo utilisent le même type d'incitation : tous `promo_offer` ou tous `plan_switch`.
- **`bullet_points`** : Jusqu'à cinq, pour un message par défaut uniquement. Chacun comporte un `text` (1 à 66 caractères), un `alt_text` facultatif et `image_path` : le chemin vers son icône PNG, relatif au dossier du fichier JSON. La CLI refuse `image_index`.
- **`localizations`** : Une entrée pour chaque locale autre que `en-US`, avec `locale`, `title`, `body`, et un texte `bullet_points` pour chaque point du message, dans le même ordre.

`--image` ajoute l'image d'un message par défaut. Un message promo n'a pas d'image ni de points.

Avant de vous demander confirmation, la CLI valide chaque fichier image. Elle demande ensuite votre approbation, comme décrit dans [Confirmation dans les scripts et agents](#confirmation-in-scripts-and-agents). Adapty envoie les textes et images du nouveau message à Apple pour révision, et l'état du message passe à `in_review`.

Si une création échoue avec une erreur réseau ou une erreur serveur, ne relancez pas la commande. Voir [Si une création ou une modification ne reçoit pas de réponse](#if-a-create-or-a-change-gets-no-answer).

### Exigences relatives aux images

| Fichier | Exigences |
|---|---|
| Image (`--image`) | PNG, 3840 px de large et 160–2160 px de hauteur, sans transparence, jusqu'à 10 Mo |
| Icône de point de liste (`image_path`) | PNG, 1024 × 1024 px, sans transparence, jusqu'à 10 Mo |

La CLI valide chaque fichier avant d'envoyer quoi que ce soit. Un PNG avec canal alpha est accepté si chaque pixel est entièrement opaque. Un PNG endommagé échoue avec l'erreur `must be a PNG`. En cas d'échec, la CLI n'envoie rien et quitte avec le code 2. L'erreur indique le fichier concerné et la règle violée, par exemple `… must be 3840 px wide and 160–2160 px tall`.

## Modifier un message \{#change-a-message\}

:::warning
Toute modification d'un message inactif le réactive, même un simple changement de nom. Une fois qu'Apple a approuvé le message, les abonnés le voient.
:::

`messages update` ne modifie que ce que vous nommez. Chaque locale, point de liste, icône, produit et image que vous ne nommez pas restent inchangés :

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

Modifier le nom, le titre, le corps, le texte alternatif et l'image avec les flags : `--name`, `--title`, `--body`, `--alt-text`, `--image`, et `--remove-image`. Modifier les locales, les points de liste et les produits avec un fichier de modifications via `--file`. Le fichier de modifications accepte également `name`, `title`, `body`, `alt_text` et `remove_image`. Le CLI refuse toute clé que le fichier de modifications ne reconnaît pas. Ce fichier de modifications s'applique au message créé dans [Créer un message](#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>"]
}
```

- **Locales** : Nommez chaque locale par son code dans `locale`, avec `title`, `body` et les textes des points de la locale dans `bullet_texts`, par `bullet_id`. Une locale que le message ne possède pas est ajoutée, et elle nécessite `title`, `body` et un texte pour chaque point.
- **Points** : Pour modifier un point, nommez-le par son `bullet_id` issu de `messages get`, avec `text`, `alt_text`, ou `image_path` pour une nouvelle icône. Un nouveau point n'a pas de `bullet_id`. Il nécessite `image_path`, le `text` en `en-US` et un texte dans `texts` pour chaque locale du message.
- **Produits** : Par leur identifiant produit App Store dans `store_id`. Un produit que le message ne possède pas est ajouté. Dans un message promo, chaque produit nécessite une offre : pour la modifier, passez une nouvelle `association`. Pour ne plus proposer d'offre sur un produit, supprimez le produit avec `remove_products`. Un produit que vous ajoutez à un message promo nécessite une `association`.
- **Suppressions** : Utilisez les champs de suppression : `remove_localizations` (codes de locale), `remove_bullet_points` (identifiants de points), `remove_products` (identifiants produit App Store), et `remove_image: true` ou `--remove-image`. Un point supprimé disparaît de toutes les locales. Tant qu'un message promo utilise un produit, vous ne pouvez pas supprimer ce produit de son message par défaut.

Vous ne pouvez pas modifier le type, le `header_position` ou le type d'incitation d'un message promo (`promo_offer` ou `plan_switch`). Pour en utiliser un différent, créez un nouveau message.

La CLI valide vos modifications avant d'envoyer quoi que ce soit. Si l'entrée se contredit, ne modifie rien, ou nomme ou supprime quelque chose que le message ne possède pas, la CLI n'envoie rien, quitte avec le code 2, et l'erreur indique le problème. Donnez les textes localisés d'un point de liste existant dans `bullet_texts` de la locale, pas dans `texts`.

La CLI demande une approbation, lit le message, y intègre vos modifications, puis envoie le message complet à Adapty. Chaque mise à jour envoie l'intégralité du message à Apple pour révision, et l'état du message passe à `in_review`. Si quelqu'un modifie le message dans le tableau de bord pendant l'exécution de `messages update`, la mise à jour écrase cette modification.

## Activer ou désactiver un message \{#activate-or-deactivate-a-message\}

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

- **`activate`** : Fait passer un message `inactive` à `in_review`. Apple ne réévalue que les locales qu'il n'a pas encore approuvées. Une fois le message approuvé par Apple, les abonnés le voient à nouveau.
- **`deactivate`** : Fait passer un message `live` à `inactive`. Les abonnés ne le voient plus. Les vues déjà enregistrées restent dans les métriques.

Adapty refuse `activate` si le message n'est pas `inactive`, et `deactivate` s'il n'est pas `live`. Un message en `in_review` passe en ligne dès qu'Apple l'approuve. Pour l'arrêter, désactivez-le après cela. La CLI ne dispose d'aucune commande pour supprimer un message.

Un produit peut avoir un message par défaut et un message promo dans chaque environnement. Adapty refuse l'activation dans ces cas :

- Un autre message du même type a été ajouté au produit pendant que ce message était inactif.
- Le message est un message promo, et l'un de ses produits n'a pas de message par défaut dans cet environnement.

Lorsqu'un message promotionnel utilise un produit, Adapty refuse de désactiver le message par défaut de ce produit. Désactivez d'abord le message promotionnel ou retirez-en le produit.

## Trouver des produits et des offres \{#find-products-and-offers\}

Pour trouver les produits que vous pouvez ajouter à un message, exécutez :

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

Lorsque vous modifiez un message, passez son identifiant dans `--message-id` pour que les produits de ce message n'apparaissent pas comme `used`. Un produit avec un `disabled_reason` ne peut pas être ajouté :

- **`used`** : Un autre message du même type dans cet environnement utilise déjà ce produit.
- **`no_default_message`** : Le produit n'a pas de message par défaut dans cet environnement et ne peut donc pas recevoir de message promotionnel.

Un message promo relie une incitation à chaque produit. Pour trouver les incitations d'un produit, transmettez l'`id` du produit issu de `products suggest`. Pour lister les offres promotionnelles du produit, exécutez :

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

Pour lister les plans vers lesquels un abonné peut basculer, exécutez :

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

`plan-switches suggest` a besoin de la [clé API App Store Connect](app-store-connect-api-key) dans les paramètres de l'application. Placez le `store_id` de l'offre ou du plan dans l'`association` du produit.

## Confirmation dans les scripts et les agents \{#confirmation-in-scripts-and-agents\}

Ces commandes modifient ce que les abonnés voient sur l'écran **Cancel Subscription**. Chacune affiche son effet et demande une approbation avant d'envoyer la modification, en `sandbox` et en `production` :

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

Le mode de demande dépend de la façon dont la commande est exécutée :

| Comment la commande s'exécute | Ce qui se passe |
|---|---|
| Dans un terminal, sans `--yes` et sans `--json` | Le CLI affiche l'effet et demande `Apply? [y/N]`. Si vous répondez `y` ou `yes`, le CLI envoie la requête. Pour toute autre réponse, le CLI quitte avec le code 1 et n'envoie rien. |
| Avec `--yes`, dans un terminal ou non | Le CLI envoie la requête sans demander, même en `production`. |
| Sans `--yes`, avec `--json`, dans un pipe, ou sans terminal | Le CLI n'envoie rien et quitte avec le code 6. L'erreur décrit l'effet. |

Remplacer une URL en temps réel différente dans Apple obéit à ses propres règles. Voir [Connecter l'URL en temps réel](#connect-the-realtime-url).

Un script ou un agent peut ainsi lire l'effet d'une commande avant de l'appliquer : exécutez-la sans `--yes`, lisez le résultat, puis relancez-la avec `--yes` seulement après approbation.

`setup-status`, `realtime-url get`, `performance-test start`, `messages list`, `messages get` et les commandes `suggest` s'exécutent sans demande de confirmation.

## Erreurs \{#errors\}

| Code de sortie | Cause | Que faire |
|---|---|---|
| 1 | Vous avez répondu autre chose que `y` à l'invite. Rien n'a été envoyé. | Relancez la commande si c'était votre intention. |
| 2 | Le CLI a refusé la saisie avant d'envoyer la modification : un flag, un fichier image, un conflit dans la saisie, une locale sans texte pour chaque point, ou la suppression d'un élément absent du message de rétention. | Corrigez ce que l'erreur indique. |
| 3 | Vous n'êtes pas connecté, ou Adapty a refusé l'accès à l'application. | Connectez-vous avec `adapty auth login` et trouvez l'ID de l'application dans `adapty apps list`. |
| 4 | Adapty a refusé la requête. L'erreur en indique la raison, et `--json` donne le statut HTTP et l'`error_code`. Une erreur serveur (5xx) lors d'une création ou d'une modification donne également le code 4, et le résultat est inconnu. | Consultez [Messages from Adapty](#messages-from-adapty). Après une erreur serveur lors d'une création ou d'une modification, consultez [If a create or a change gets no answer](#if-a-create-or-a-change-gets-no-answer). |
| 5 | Le CLI n'a pas pu joindre Adapty. | Vérifiez que vous êtes en ligne. Après une création ou une modification, consultez [If a create or a change gets no answer](#if-a-create-or-a-change-gets-no-answer). |
| 6 | Une commande nécessitant une confirmation a été exécutée sans `--yes` et sans personne pour répondre, ou un remplacement d'URL en temps réel a été effectué sans `--replace-other-url`. Rien n'a été envoyé. | Lisez l'effet décrit dans l'erreur, puis relancez la commande avec `--yes`, et avec `--replace-other-url` pour un remplacement. |
| 130 | Vous avez appuyé sur Ctrl+C à l'invite. Rien n'a été envoyé. | — |

### Messages d'Adapty

Avec `--json`, l'erreur renvoie l'`error_code` :

| `error_code` | Cause | What to do |
|---|---|---|
| `app_store_credentials_missing` | L'application n'a pas de clés App Store dans Adapty. | Complétez la [configuration App Store](app-store-connection-configuration). |
| `app_store_connect_credentials_missing` | `plan-switches suggest` nécessite la clé API App Store Connect. | Ajoutez la [clé API App Store Connect](app-store-connect-api-key). |
| `realtime_url_unavailable` | L'application n'a pas de configuration de notifications serveur App Store dans Adapty. | Complétez la [configuration App Store](app-store-connection-configuration). |
| `apple_rm_api_access_denied` | Apple n'a pas accordé à l'application l'accès à l'API Retention Messaging. | [Demandez l'accès à Apple](retention-messaging-setup#request-access-from-apple). |
| `performance_test_required` | Vous avez configuré `production` avant que le test de performance soit réussi. | [Exécutez d'abord le test de performance](#run-the-performance-test). |
| `performance_test_already_running` | Un test de performance est en cours. | Attendez, puis relisez le statut de configuration. |
| `active_sandbox_transaction_missing` | Aucun abonnement sandbox actif. | Achetez votre produit à la durée la plus longue en sandbox, puis relancez le test. |
| `performance_test_request_rejected` | Apple a refusé de démarrer le test. | Effectuez un nouvel achat sandbox, puis relancez le test. |
| `retention_product_claimed` | Un autre message du même type possède déjà ce produit. | Choisissez un autre produit ou désactivez l'autre message. |
| `retention_default_message_missing` | Un message promo a un produit sans message par défaut. | Créez ou activez d'abord un message par défaut pour ce produit. |
| `retention_dependent_promo_messages` | Un message promo utilise un produit que la modification retirerait d'un message par défaut. | Désactivez le message promo, ou retirez-en le produit, d'abord. |
| `retention_promo_association_invalid` | Un message promo n'a pas de produit, un produit sans `association`, ou les deux types d'incentive. | Attribuez à chaque produit une `association` du même type. |
| `retention_message_type_immutable` | La modification donne à un message promo un type d'incentive différent. | Créez un nouveau message. |
| `retention_message_invalid_status_transition` | `activate` sur un message qui n'est pas `inactive`, ou `deactivate` sur un message qui n'est pas `live`. | Lisez l'état du message avec `messages get`. |
| `retention_message_not_found` | L'application n'a aucun message avec cet ID. | Prenez l'ID depuis `messages list`. |

### Si une création ou une modification reste sans réponse \{#if-a-create-or-a-change-gets-no-answer\}

Si le CLI ne reçoit aucune réponse à une création ou une mise à jour, en raison d'une erreur réseau ou d'une erreur serveur (code de sortie 4 ou 5), il ne peut pas savoir si Adapty a enregistré la modification. Le CLI ne renvoie pas la requête. Ne relancez pas vous-même la commande non plus.

- **Après une création** : Exécutez `messages list` pour le même environnement avec `--search "<name>" --page-size 100`. L'erreur affiche le nom exact sur sa propre ligne (`message_name` dans `--json`). Parcourez toutes les pages jusqu'à `meta.pagination.pages`, et ouvrez chaque candidat avec `messages get`. Une seconde création peut générer un message en doublon et l'envoyer en révision chez Apple. Ne recréez le message que si aucun candidat ne correspond au vôtre.
- **Après une mise à jour** : Exécutez `messages get`, et lisez l'état et le contenu du message.

## Référence des commandes \{#command-reference\}

Chaque commande prend `--app`, l'UUID de l'application issu de `adapty apps list`.

### `retention-messaging setup-status`

Renvoie l'état de configuration. Ne prend aucun autre indicateur.

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

Renvoie l'URL temps réel d'Adapty. Ne prend aucun autre paramètre.

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

| Flag | Requis | Description |
|---|---|---|
| `--mode` | Oui | `sandbox` ou `production`. |
| `--replace-other-url` | Non | Approuver le remplacement d'une URL différente dans Apple. |
| `--yes`, `-y` | Non | Configurer sans demander de confirmation. Requis avec `--json` ou dans un pipe. |

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

Lance le test de performance d'Apple en `sandbox`. Ne prend aucun autre paramètre.

### `retention-messaging messages list`

| Flag | Required | Description |
|---|---|---|
| `--mode` | Oui | `sandbox` ou `production`. |
| `--search` | Non | Une partie du nom, quelle que soit la casse, ou l'ID exact du message. |
| `--type` | Non | `default` ou `promo`. |
| `--state` | Non | `in_review`, `live`, `rejected` ou `inactive`. |
| `--ordering` | Non | `name`, `type`, `state`, `products_count` ou `started_at`. Ajoutez `-` avant le champ pour l'ordre inverse. Valeur par défaut : `-started_at`. |
| `--page` | Non | Numéro de page. Valeur par défaut : 1. |
| `--page-size` | Non | Messages par page, jusqu'à 100. Valeur par défaut : 20. |

### `retention-messaging messages get`

Prend l'ID du message comme argument. Retourne le message complet.

### `retention-messaging messages create`

| Indicateur | Requis | Description |
|---|---|---|
| `--mode` | Oui | `sandbox` ou `production`. |
| `--file` | Oui | Le fichier JSON du message, ou `-` pour le lire depuis l'entrée standard. Voir [Créer un message](#create-a-message). |
| `--image` | Non | L'image PNG d'un message par défaut. |
| `--yes`, `-y` | Non | Créer sans confirmation. Requis avec `--json` ou dans un pipe. |

### `retention-messaging messages update`

Prend l'ID du message comme argument.

| Flag | Requis | Description |
|---|---|---|
| `--name`, `--title`, `--body`, `--alt-text` | Non | Nouvelle valeur du champ. |
| `--image` | Non | Nouvelle image PNG. |
| `--remove-image` | Non | Supprimer l'image. |
| `--file` | Non | Le fichier de modifications, ou `-` pour le lire depuis l'entrée standard. Voir [Modifier un message](#change-a-message). |
| `--yes`, `-y` | Non | Modifier sans confirmation. Requis avec `--json` ou dans un pipe. |

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

Prend l'ID du message comme argument.

| Indicateur | Requis | Description |
|---|---|---|
| `--action` | Oui | `activate` ou `deactivate`. |
| `--yes`, `-y` | Non | Change le statut sans demander de confirmation. Requis avec `--json` ou dans un pipe. |

### `retention-messaging products suggest`

| Indicateur | Requis | Description |
|---|---|---|
| `--mode` | Oui | `sandbox` ou `production`. |
| `--type` | Oui | `default` ou `promo` : le type du message. |
| `--search` | Non | Une partie du titre du produit, toute casse. |
| `--message-id` | Non | L'ID du message à modifier. |
| `--limit` | Non | Produits à retourner, jusqu'à 100. Par défaut : 10. |

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

Prend l'ID produit retourné par `products suggest` comme argument.

| Indicateur | Requis | Description |
|---|---|---|
| `--search` | Non | Partie du titre de l'offre, insensible à la casse. |
| `--limit` | Non | Nombre d'offres à retourner, jusqu'à 100. Défaut : 10. |

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

Prend l'identifiant du produit retourné par `products suggest` comme argument.

| Flag | Obligatoire | Description |
|---|---|---|
| `--search` | Non | Une partie du titre du plan, sans respect de la casse. |
| `--limit` | Non | Nombre de plans à retourner, jusqu'à 100. Par défaut : 10. |

## Travailler depuis un assistant IA \{#work-from-an-ai-assistant\}

Le [serveur MCP Adapty](adapty-mcp) propose les mêmes actions que les outils `retention_messaging_*`, par exemple `retention_messaging_messages_list` pour `messages list`. Les outils prennent `message_type` à la place de `--type`.

- **Approbation** : L'assistant demande confirmation avant de configurer l'URL en temps réel, de créer ou modifier un message, ou de changer son statut, en `sandbox` et en `production`. Avant de remplacer l'URL en temps réel d'un autre serveur, il pose une question distincte. Il demande également une fois par conversation avant sa première lecture du statut de configuration, et une fois avant sa première lecture des messages, car [ces lectures peuvent mettre à jour Adapty](#read-the-setup-status).
- **Images et puces** : Les outils MCP ne peuvent pas ajouter d'image, d'icône de puce ou de nouvelle puce. `retention_messaging_messages_create` crée un message sans image ni puces. Pour en ajouter, exécutez `messages update` depuis la CLI ou utilisez le tableau de bord.

## Et ensuite ? \{#whats-next\}

- [Skill agent pour la Retention Messaging](retention-messaging-skill) — laissez votre agent configurer la Retention Messaging et rédiger vos messages, avec votre validation à chaque modification.
- [Configurer la Retention Messaging](retention-messaging-setup) — les mêmes étapes de configuration dans le tableau de bord.
- [Créer un message de rétention](retention-messaging-create) — les champs du message, les langues et les états dans le tableau de bord.
- [Suivre les performances des messages](retention-messaging-analytics) — ce que signifie chaque métrique.