> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Opt-outs e respostas STOP

> Como a Polymorfa suprime destinatários de campanhas, captura respostas STOP e START e avisa a sua integração sobre as duas.

A lista de opt-outs é a lista de supressão da sua equipe: números para os quais
as campanhas não podem enviar mensagens. Ela vale para a equipe inteira, então
um número que faz opt-out da campanha de um projeto fica suprimido em todos os
projetos dessa equipe.

A Polymorfa aplica a lista em dois momentos e a mantém atualizada a partir das
respostas dos seus próprios contatos.

## Onde a lista é aplicada

| Quando | O que acontece |
| - | - |
| Uma campanha é lançada | Todo destinatário que está na lista de opt-outs é marcado como `skipped` com `failureReason` `opted_out` e contado uma vez em `skippedCount` |
| Um destinatário está prestes a receber o envio | Um número que está na lista nunca é reservado para envio, qualquer que seja o status do destinatário |

Como a segunda verificação acontece no momento do envio, um número adicionado à
lista depois do lançamento de uma campanha também fica suprimido. Colocar de
novo na fila um destinatário ignorado não envia para um número que está na
lista.

## Gerencie a lista diretamente

```bash theme={null}
# Add one number
curl -X POST "https://api.polymorfa.com/platform/optouts" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550100" }'

# Read the list
curl "https://api.polymorfa.com/platform/optouts" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

# Remove one number
curl -X DELETE "https://api.polymorfa.com/platform/optouts/%2B14155550100" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

`POST /platform/optouts/batch` recebe um array `phones` e adiciona até 1.000
números em uma solicitação. A leitura exige uma chave de API da equipe com
`campaigns:read`; toda alteração exige `campaigns:manage`. Tokens de projeto são
recusados nas rotas de opt-out.

## Respostas STOP e START

Com a captura de palavras-chave ativada, um contato que responde `STOP` a uma
das mensagens das suas campanhas entra na lista de opt-outs, e um contato que
responde `START` sai dela.

Uma resposta só altera a lista quando todas as condições abaixo são atendidas:

* É uma mensagem de texto direta, não uma mensagem de grupo.
* A mensagem inteira corresponde a uma palavra-chave configurada. A comparação
  ignora maiúsculas e minúsculas e a pontuação e os espaços ao redor, então
  `STOP`, `stop` e `stop!` correspondem. `please stop` não corresponde.
* O número que respondeu recebeu uma mensagem de campanha da sua equipe nos
  últimos 30 dias.

Uma palavra-chave de opt-in remove apenas um opt-out criado por uma resposta com
palavra-chave. Um opt-out que você adicionou manualmente, por arquivo ou pela API
nunca é removido por uma resposta, então uma supressão explícita continua
valendo.

A Polymorfa compara o corpo da mensagem em memória e o descarta. O corpo nunca é
armazenado, e os eventos abaixo trazem a palavra-chave que correspondeu, nunca a
mensagem.

## Configure as palavras-chave

```bash theme={null}
curl "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```json theme={null}
{
  "data": {
    "enabled": true,
    "optOutKeywords": ["STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END", "QUIT",
                       "PARAR", "SAIR", "CANCELAR", "DESCADASTRAR", "BAJA"],
    "optInKeywords": ["START", "UNSTOP"],
    "updatedAt": null
  }
}
```

Esses são os valores padrão. `updatedAt` é `null` até você salvar as suas
próprias configurações. `PUT` substitui os três campos de uma vez: envie todos
eles e nada mais, porque um campo não reconhecido faz a solicitação falhar.

```bash theme={null}
curl -X PUT "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "optOutKeywords": ["STOP", "UNSUBSCRIBE", "PARAR"],
    "optInKeywords": ["START"]
  }'
```

| Regra | Valor |
| - | - |
| Palavras-chave por lista | No máximo 50 |
| Tamanho da palavra-chave | De 1 a 32 caracteres depois de remover a pontuação e os espaços ao redor |
| `optOutKeywords` | Pelo menos uma palavra-chave |
| Palavras-chave em comum | As duas listas não podem ter uma palavra-chave em comum |
| Armazenamento | As palavras-chave são armazenadas em maiúsculas |
| Propagação | Uma alteração passa a valer para as respostas em até 30 segundos |

Defina `enabled` como `false` para parar de ler as respostas em busca de
palavras-chave. A lista de opt-outs continua funcionando: as entradas existentes
continuam suprimidas e a API ainda adiciona e remove números.

Ler as configurações exige `campaigns:read`; alterá-las exige
`campaigns:manage`. Os dois exigem uma chave de API da equipe.

## Confirmações de saída opcionais

> [!NOTE]
>
> As confirmações de saída exigem acesso ao beta. Elas ficam desativadas por
> padrão, inclusive para equipes inscritas. Ler a preferência e desativá-la
> continuam disponíveis quando o acesso ao beta termina.

Um proprietário ou administrador da equipe pode ativar as confirmações em
**Campanhas → Opt-outs** e escolher inglês, português do Brasil ou espanhol. A
confirmação usa um texto fixo nesse idioma, sem links, mídia ou conteúdo
promocional.

As confirmações valem apenas para um novo opt-out capturado de uma resposta com
palavra-chave correspondente. Mensagens STOP duplicadas, uma supressão existente
e opt-outs adicionados manualmente ou por importação não geram confirmações. Um
START posterior seguido de um novo STOP pode criar um novo opt-out e uma nova
confirmação.

A conexão que recebeu a resposta precisa continuar conectada e apta a enviar.
Uma confirmação é enviada em até cinco minutos após a resposta original, pela
mesma conexão. Saldo, restrições do provedor e proteções de envio continuam
valendo. Números de dispositivo vinculado independentes e números da API oficial
são compatíveis; números Hybrid Link e números de teste não enviam confirmações.

Se o envio da confirmação falhar ou tiver resultado desconhecido, a supressão
continua registrada. Um envio incerto nunca é reenviado. As contagens de
resultados cobrem 30 dias; **Aceitas pelo provedor** não confirma a entrega.

Use [Ler as configurações de confirmação](/api-reference/platform/opt-outs/get-stop-confirmation-settings)
antes de [atualizar a preferência](/api-reference/platform/opt-outs/update-stop-confirmation-settings).
Envie o `teamId` e a `revision` retornados com os valores escolhidos de
`enabled` e `locale`. Uma revisão desatualizada retorna `409`; leia de novo antes
de decidir se vai salvar outra alteração. A leitura exige `campaigns:read`, e
alterar a preferência exige `campaigns:manage` em uma chave da equipe.

```bash theme={null}
curl -X PUT "https://api.polymorfa.com/platform/optouts/confirmation-settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"019d0000-0000-7000-8000-000000000002","revision":0,"enabled":false,"locale":null}'
```

Substitua a equipe e a revisão do exemplo pelas que a sua leitura das
configurações retornou. Este exemplo mantém as confirmações desativadas.

Quando a CLI instalada incluir os comandos de confirmação de STOP, leia a equipe
e a revisão e depois salve uma escolha explícita:

```bash theme={null}
polymorfa optout confirmations view
polymorfa optout confirmations update \
  --team-id 019d0000-0000-7000-8000-000000000002 \
  --revision 0 --enabled --locale pt-BR
polymorfa optout confirmations summary --json
```

Use o `teamId` e a `revision` do seu próprio resultado de `view`. Para desativar
as confirmações, execute `update` com `--no-enabled` e omita `--locale`. A CLI
envia uma solicitação de atualização; depois de um erro ou de um tempo esgotado,
leia a configuração antes de fazer outra alteração.

## Eventos de webhook

Assine `contact.opted_out` e `contact.opted_in` para refletir as alterações por
palavra-chave no seu próprio sistema.

```json theme={null}
{
  "id": "01995b51-bc80-7000-8000-000000000001",
  "session": "sales-1",
  "timestamp": "2026-09-20T10:15:30.000Z",
  "event": "contact.opted_out",
  "payload": {
    "phone": "+14155550100",
    "source": "stop-keyword",
    "keyword": "STOP",
    "session": "sales-1",
    "projectId": "0b0b6a36-33d2-4f1e-9a10-2f7a1f0d55c1"
  }
}
```

`source` é sempre `stop-keyword`: esses dois eventos informam respostas com
palavra-chave, não alterações que você faz pela API ou pelo Console. `keyword` é
a palavra-chave configurada que correspondeu, em maiúsculas. Consulte
[Webhooks](/api/webhooks#current-event-catalog).


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