Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

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.

Ver em Markdown

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#

QuandoO que acontece
Uma campanha é lançadaTodo 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 envioUm 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#

Shell
# 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, 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#

cURL
curl "https://api.polymorfa.com/platform/optouts/settings" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const settings = await platform.optOuts.getSettings();
console.log(settings.data.data.enabled, settings.data.data.optOutKeywords);
JSON
{
  "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
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"]
  }'
TypeScript
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.

RegraValor
Palavras-chave por listaNo máximo 50
Tamanho da palavra-chaveDe 1 a 32 caracteres depois de remover a pontuação e os espaços ao redor
optOutKeywordsPelo menos uma palavra-chave
Palavras-chave em comumAs duas listas não podem ter uma palavra-chave em comum
ArmazenamentoAs palavras-chave são armazenadas em maiúsculas
PropagaçãoUma 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.

Shell
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:

Shell
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
{
  "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.