# Retention Messaging API: a mensagem antes do cancelamento

> A Retention Messaging API da Apple mostra sua mensagem quando o assinante toca em Cancel Subscription. Formatos, regras, acesso e configuração.

Página original: [Retention Messaging API: a mensagem antes do cancelamento](https://devoria.fr/pt-br/blog/retention-messaging-api-mensagem-antes-cancelamento)
Autor: [Mehdi Azizi](https://devoria.fr/pt-br/mehdi-azizi)
Publicação: 2026-11-04
Última revisão do conteúdo: 2026-11-04


A Retention Messaging API é um serviço da Apple, de servidor para servidor, que mostra sua mensagem a um assinante no momento em que ele toca em Cancel Subscription. A mensagem aparece numa página de confirmação, antes de o cancelamento ser concluído. **Ela pode lembrar o valor da sua assinatura, sugerir outro plano ou uma oferta promocional, mas o botão para cancelar continua sempre lá.** A API está em pré-lançamento desde julho de 2025, com acesso mediante solicitação, e a Apple anunciou uma versão mais simples no App Store Connect para o outono (do hemisfério norte) de 2026.

Este guia explica o que a API mostra, desde quando ela existe, quem pode usar, quais são as regras e como configurar. Tudo vem da documentação da Apple e da sessão da WWDC26 dedicada a ela, relidas em 3 de novembro de 2026.

Eu vendo assinaturas nos meus apps iOS: Solys, um bloqueador de redes sociais, TradaZen, um simulador de trading, Nolera, um app de provador de roupas com IA, e Vigie. Pedi acesso à API para os quatro em 25 de outubro de 2026 e preparei as mensagens em todos os idiomas deles. Em 28 de outubro, a aprovação da Apple ainda não tinha chegado. Então este guia descreve a regra e a minha preparação, ainda não resultados.

## O que a Retention Messaging API faz

Segundo a [documentação da Apple](https://developer.apple.com/documentation/retentionmessaging), a API deixa você escolher a mensagem que o sistema mostra quando um cliente abre a página de detalhes de uma assinatura e talvez esteja prestes a cancelar. Você prepara as mensagens com antecedência, para cada produto e cada idioma.

O fluxo é sempre o mesmo:

1. O assinante abre a assinatura, por exemplo em Apple Account, Subscriptions, ou pela App Store.
2. Ele toca em Cancel Subscription.
3. O sistema mostra uma página de confirmação (Confirm Cancellation), com a sua mensagem.
4. Ele pode cancelar mesmo assim, manter a assinatura ou aceitar o que a sua mensagem propõe.

A mensagem aparece no iOS 15.1 e iPadOS 15.1 ou mais recente, no visionOS 1 e no macOS 14 ou mais recente.

## Desde quando, e para quem

| Data         | O que muda, segundo a Apple                                           |
| ------------ | --------------------------------------------------------------------- |
| 16 jul. 2025 | Versão 1.0: primeiro pré-lançamento da API                            |
| 9 dez. 2025  | Teste de desempenho do servidor para o tempo real                     |
| 31 mar. 2026 | Tópicos nas mensagens, configuração do endereço em tempo real via API |
| 27 abr. 2026 | Suporte a assinaturas mensais com compromisso de 12 meses             |
| Jun. 2026    | WWDC26: anúncio de um módulo no App Store Connect                     |

As datas vêm do [histórico de versões da API](https://developer.apple.com/documentation/retentionmessaging/retention-messaging-changelog), exceto a última, tirada da sessão da WWDC26. A API continua em pré-lançamento: a documentação aponta para um [formulário de solicitação de acesso](https://developer.apple.com/contact/request/retention-messaging-api/), que exige login na sua conta de desenvolvedor.

Na WWDC26, a sessão [Explore Retention Messaging in App Store Connect](https://developer.apple.com/videos/play/wwdc2026/309/) apresenta um módulo configurável sem código, dentro do App Store Connect. A Apple diz que ele é "aberto a todos". Já a versão em tempo real continua mediante solicitação. A [página de novidades da App Store](https://developer.apple.com/app-store/whats-new/) anuncia o módulo para "este outono". **Em 3 de novembro de 2026, a ajuda do App Store Connect ainda não tem nenhuma página sobre ele, e o módulo não aparecia na minha conta em 28 de outubro.**

A API é para apps que vendem uma assinatura com renovação automática. Não é exclusiva de grandes empresas: a RevenueCat observa no seu [estudo com 22 milhões de mensagens](https://www.revenuecat.com/blog/growth/apple-retention-messaging-benchmarks) que apps pequenos também podem pedir acesso.

## Os 4 tipos de mensagem

| Tipo               | O que o assinante vê                                    | Mensagem padrão | Tempo real |
| ------------------ | ------------------------------------------------------- | --------------- | ---------- |
| Texto              | Um título, um texto, até cinco tópicos                  | Sim             | Sim        |
| Texto com imagem   | O mesmo, com uma imagem                                 | Sim             | Sim        |
| Mudança de plano   | Um texto e outra assinatura do mesmo grupo              | Não             | Sim        |
| Oferta promocional | Um texto e uma oferta para continuar com preço reduzido | Não             | Sim        |

Segundo a página sobre a [preparação das mensagens](https://developer.apple.com/documentation/retentionmessaging/setting-up-retention-messages), uma mensagem padrão só pode ser um texto, com ou sem imagem. **Com a API, oferecer uma oferta ou outro plano exige responder em tempo real.** Já o módulo anunciado no App Store Connect vai permitir uma mensagem com oferta, sem servidor.

A oferta promocional é aquela que você cria no App Store Connect. Segundo a [ajuda sobre ofertas promocionais](https://developer.apple.com/help/app-store-connect/manage-subscriptions/set-up-promotional-offers-for-auto-renewable-subscriptions), ela é voltada para assinantes atuais e antigos. Numa mensagem de retenção, quem assina a oferta é o seu servidor, segundo a página sobre a preparação das mensagens. A mudança de plano propõe uma assinatura do mesmo grupo. Se você está começando com essas ofertas, leia antes meu guia sobre códigos de oferta e ofertas promocionais.

## O que você pode mostrar: os limites exatos

| Elemento                | Limite da Apple                                                   |
| ----------------------- | ----------------------------------------------------------------- |
| Título                  | No máximo 66 caracteres                                           |
| Texto                   | No máximo 144 caracteres                                          |
| Tópicos                 | No máximo 5                                                       |
| Imagem de largura total | PNG sem transparência, 3.840 px de largura, 160 a 2.160 de altura |
| Imagem de tópico        | 1.024 × 1.024 px                                                  |
| Imagens por app         | No máximo 2.000                                                   |

Os tamanhos vêm da descrição do [corpo da requisição de envio de mensagem](https://developer.apple.com/documentation/retentionmessaging/uploadmessagerequestbody), e os formatos da página sobre o [envio de imagem](https://developer.apple.com/documentation/retentionmessaging/upload-image). A Apple também pede imagens que funcionem tanto no modo claro quanto no modo escuro.

Cada mensagem e cada imagem passam por revisão da Apple. O status vai de `PENDING` para `APPROVED`, e o sistema só mostra o que foi aprovado. No sandbox, a aprovação é automática. A documentação traz uma regra de conteúdo clara: não enviar nada enganoso ou impreciso.

## As condições a cumprir

- **Uma mensagem padrão para cada produto, em cada idioma.** Sem ela, nada aparece naquele idioma. Ela também é o plano B se o seu servidor não responder.
- **Mensagens e imagens aprovadas** antes de qualquer publicação.
- **Para o tempo real, um servidor rápido.** A página sobre a [configuração do endereço em tempo real](https://developer.apple.com/documentation/retentionmessaging/setting-up-retention-messaging-endpoint) exige um certificado SSL válido, TLS 1.2 e resposta em menos de 700 ms em produção. Passou disso, a requisição falha e a mensagem padrão aparece.
- **Um teste de desempenho aprovado no sandbox**, antes de registrar seu endereço de produção.
- **Uma verificação do app.** Cada requisição da Apple traz o identificador do app, `appAppleId`. Se ele não bater com o seu, a Apple pede para você não responder.

A requisição em tempo real te passa o identificador da transação original, o produto e o idioma do aparelho. Cabe a você escolher a mensagem, segundo as suas regras.

## Configurar a Retention Messaging: três caminhos

| Caminho                     | Para quem                      | O que precisa                                        |
| --------------------------- | ------------------------------ | ---------------------------------------------------- |
| Módulo do App Store Connect | Todo mundo, quando for lançado | Nenhum código; texto, imagem ou oferta               |
| API, com seu servidor       | Quem tem um back-end           | Acesso da Apple, endereço HTTPS, teste de desempenho |
| API, pela RevenueCat        | Apps que já usam RevenueCat    | Acesso da Apple, configurações no painel             |

Quando várias configurações coexistem, a Apple explica na sessão da WWDC26 a ordem seguida: primeiro a resposta em tempo real. Se ela faltar ou vier malformada, a configuração do App Store Connect. Se ela não existir, a mensagem padrão configurada pela API.

### Com o seu próprio servidor

1. Peça acesso pelo formulário da Apple.
2. Envie suas imagens e depois suas mensagens, com um título e um texto para cada uma.
3. Espere a aprovação e depois registre uma mensagem padrão para cada assinatura e cada idioma.
4. Para o tempo real, crie o endereço `Get Retention Message` no seu servidor e registre-o no sandbox.
5. Rode o [teste de desempenho](https://developer.apple.com/documentation/retentionmessaging/initiate-performance-test), no sandbox, com uma transação de teste.
6. Depois que o teste passar, registre seu endereço de produção.

### Com a RevenueCat

Foi o caminho que eu escolhi: nenhum servidor para escrever, e meus apps já passam pela RevenueCat, como explico em [RevenueCat e a assinatura in-app no iOS](https://devoria.fr/pt-br/blog/revenuecat-assinatura-in-app-ios). Segundo a [documentação da RevenueCat](https://www.revenuecat.com/docs/platform-resources/apple-platform-resources/apple-retention-messaging-api):

1. No formulário da Apple, o endereço a informar é o que a RevenueCat mostra nas configurações do seu app da App Store.
2. Depois da aprovação, abra Lifecycle, depois Retention, e conecte o endereço do sandbox.
3. Rode o teste de desempenho com uma assinatura ativa de sandbox ou TestFlight. Ele pode levar até uma hora.
4. Crie primeiro uma mensagem padrão, idioma por idioma.
5. Depois adicione mensagens em tempo real, com regras. Uma delas, "Is in free trial", é voltada para quem está no teste grátis.
6. Passe para produção: as configurações do sandbox não são aproveitadas, é preciso recriar as mensagens.

## Escrever uma mensagem que retém sem enganar

O texto é fixo e revisado pela Apple antes de aparecer. Então ele não pode falar da pessoa que está lendo, nem do dia em que ela lê. Esta é a mensagem padrão que preparei para o TradaZen, em francês, aqui adaptada para o português:

```text
Título (59 caracteres):
Você queria aprender a operar e agora vai seguir no escuro?

Texto (118 caracteres):
Sem treino, seu dinheiro real paga cada erro. Aqui, eles não custam nada. Sua sequência, sua liga e suas lições param.
```

As regras que defini para os meus quatro apps:

- **O título lembra a pessoa do objetivo dela**, em forma de pergunta. Não faz ela sentir vergonha.
- **O texto diz o que para, exatamente.** Escrevo que o acesso "fica bloqueado" quando os dados continuam lá, nunca que eles serão "apagados".
- **Nenhuma palavra de tempo** como "amanhã" ou "hoje": o mesmo texto aparece em qualquer momento do período.
- **Nenhuma promessa de ganho**, nenhuma falsa urgência. Um primeiro título que prometia mudar de vida com o trading foi descartado antes do envio. A [guideline 5.6](https://developer.apple.com/app-store/review/guidelines/#5.6) proíbe qualquer prática manipuladora, e o paywall do TradaZen já foi rejeitado por esse motivo, como conto em a guideline 5.6 e o paywall.
- **Cada idioma tem o seu texto**, com o vocabulário do app traduzido, e contado caractere por caractere.

Para o TradaZen, também planejo uma mensagem em tempo real para quem está no teste da assinatura anual. Ela vai propor um plano anual mais barato do mesmo grupo, porque meus números mostram que essas pessoas usam o app tanto quanto quem paga: é o preço que elas recusam. Essa configuração está esperando a aprovação da Apple.

## O que dá para esperar

Não conte com milagre. A Apple chama de taxa de recuperação a parcela de assinantes que mantêm a assinatura depois de chegar à página de confirmação. Na sessão da WWDC26, a Apple anuncia que as assinaturas que adotaram a Retention Messaging ganham em média 1,4 ponto nessa taxa. As mensagens com oferta promocional têm o melhor ganho observado, 5,5 pontos, e os resultados variam de um desenvolvedor para outro. Já o estudo da RevenueCat aponta que os assinantes aceitam só cerca de 1,1% das ofertas promocionais e 0,6% das mudanças de plano.

Então a mensagem não substitui o trabalho feito antes. Um teste grátis cancelado no primeiro minuto se decide no paywall e nas primeiras sessões: as causas e as alavancas estão no meu guia sobre [teste grátis cancelado](https://devoria.fr/pt-br/blog/teste-gratis-cancelado-na-hora-ios), e a criação do teste na oferta introdutória.

## Prepare sua assinatura antes da mensagem

O [iOS & Android Kit](https://devoria.fr/pt-br/kits/ios) parte do código-base dos meus apps: onboarding, paywall e assinaturas já vêm prontos, e o roteiro em quatro etapas te leva até a App Store, no seu ritmo. A cadeia toda, dos produtos no App Store Connect ao paywall, está descrita na página [assinatura in-app no iOS](https://devoria.fr/pt-br/expertise/assinatura-no-app-ios).

Se você está preparando seu primeiro lançamento, [faça seu diagnóstico gratuito](https://devoria.fr/pt-br/diagnostic): ele te diz o que realmente está travando seu projeto e te envia meu checklist anti-rejeição da Apple.

## Perguntas frequentes

### O que é a Retention Messaging API da Apple?

É um serviço de servidor para servidor que escolhe a mensagem mostrada a um assinante quando ele toca em Cancel Subscription. A mensagem aparece numa página de confirmação, antes do cancelamento. Ela pode lembrar o valor da assinatura, sugerir outro plano ou uma oferta promocional.

### A Retention Messaging está disponível para todos os desenvolvedores?

A API está em pré-lançamento, com acesso mediante solicitação à Apple. Na WWDC26, a Apple anunciou um módulo no App Store Connect, aberto a todos, previsto para o outono de 2026. Em 3 de novembro de 2026, a ajuda do App Store Connect ainda não o descreve.

### Em quais versões do iOS a mensagem aparece?

No iOS 15.1 e iPadOS 15.1 ou mais recente, no visionOS 1 e no macOS 14 ou mais recente. Num aparelho mais antigo, o cancelamento acontece sem mensagem.

### A mensagem impede o assinante de cancelar?

Não. A página de confirmação mantém um botão para cancelar. O assinante também pode manter a assinatura ou aceitar a oferta ou o plano proposto.

### Dá para oferecer um desconto no momento do cancelamento?

Sim. Com a API, é uma mensagem de oferta promocional, só em tempo real: a oferta é criada no App Store Connect e assinada pelo seu servidor. O módulo anunciado no App Store Connect também permite uma mensagem com oferta. Já a mudança de plano propõe outra assinatura do mesmo grupo.

### Quantos caracteres tem uma mensagem de retenção?

O título tem no máximo 66 caracteres, o texto 144. Você pode adicionar até cinco tópicos e uma imagem PNG sem transparência. Cada idioma precisa da sua própria mensagem padrão.

### Preciso de um servidor para usar a Retention Messaging?

Para as mensagens padrão, não há endereço para hospedar: basta chamar a API para enviá-las e registrá-las. Com a RevenueCat, é ela que faz o papel do servidor. O tempo real exige um endereço HTTPS que responda em menos de 700 ms. O módulo anunciado no App Store Connect é configurado sem código.


## Seu projeto

[iOS & Android Kit](https://devoria.fr/pt-br/kits/ios): Crie seu app para iPhone e Android com o Claude Code: o código inicial dos meus apps, o caminho até as lojas e todos os kits. R$ 589.

[Diagnóstico: o que te separa do seu app de iPhone](https://devoria.fr/pt-br/diagnostic): 7 perguntas, 60 segundos: descubra o que realmente te impede de publicar seu app de iPhone, seu caminho em 4 etapas e o kit certo para você.