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#
# 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"API Create opt outs 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,stopestop!correspondem.please stopnã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#
curl "https://api.polymorfa.com/platform/optouts/settings" \
-H "Authorization: Bearer $POLYMORFA_KEY"const settings = await platform.optOuts.getSettings();
console.log(settings.data.data.enabled, settings.data.data.optOutKeywords);{
"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.
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"]
}'await platform.optOuts.updateSettings({
enabled: true,
optOutKeywords: ["STOP", "UNSUBSCRIBE", "PARAR"],
optInKeywords: ["START"],
});TypeScript:
updateSettings também substitui os três campos. Os métodos de opt-out exigem uma chave da equipe no cliente da equipe; tokens de projeto são recusados.
| 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#
Um proprietário ou administrador da equipe pode ativar as confirmações em Campanhas → Configurações, em Confirmações de saída, 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 antes de atualizar a preferência. 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.
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.
TypeScript:
A partir da versão 0.1.0-dev.20261005233122 do SDK, o cliente da equipe tem optOuts.getConfirmationSettings, optOuts.updateConfirmationSettings e optOuts.getConfirmationSummary. Esses métodos preservam o envelope da API em response.data.data. Use o teamId e a revision retornados ao gravar uma preferência e escolha en, pt-BR ou es antes de ativar. Uma revisão desatualizada exige uma nova leitura. Nunca tente novamente de forma automática um salvamento de preferência incerto; leia a preferência salva para confirmar o resultado.
Com um pacote mais antigo, chame as mesmas rotas com platform.raw.request. Atualizar o pacote não ativa as confirmações nem concede acesso ao beta.
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:
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 --jsonUse 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.
{
"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 Tipos de evento.