> ## 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.

# Campanhas e segurança do número

> O que uma campanha verifica antes de enviar: a exigência de plano, os tetos de vazão, a lista de opt-outs, as retenções por destinatário, o aquecimento de um número novo e a situação de um número oficial do WhatsApp Business.

Campanhas é o único caminho de envio em massa da Polymorfa. Um loop sobre
`POST /api/messages/send` abre a constatação `bulk_outside_campaigns` no número
que o executa. Por isso, mensagens para pessoas que não escreveram primeiro
pertencem a uma campanha, onde o ritmo, os limites por número, a lista de
opt-outs e a verificação de contato são aplicados para você. Consulte
[Constatações](/guides/safety/findings) e
[Envie uma campanha](/pt-br/guides/campaigns/send-a-campaign).

Esta página descreve cada verificação pela qual passa um envio de campanha e a
recusa exata que você recebe quando uma delas falha. Cada código está listado em
[Erros](/api/errors#bansafe-and-safe-mode-codes).

As duas superfícies públicas executam essas verificações. Uma campanha se
comporta da mesma forma tenha sido criada e lançada por
`/messaging/projects/{projectSlug}/campaigns` ou por `/platform/campaigns`.

## Campanhas é um recurso do Pro

As campanhas enviam a partir de números em um plano que inclui Campanhas. Você
pode criar e editar um rascunho no Free ou no Standard, e um rascunho pode
selecionar números de qualquer plano. No console, números Free e Standard
aparecem desativados na seleção de remetentes, com uma ação de upgrade.

No lançamento, cada número selecionado com `senderConfig.sessionIds` precisa
estar no projeto, estar conectado e estar em um plano que inclui Campanhas, e
todos os números selecionados precisam usar um único tipo de envio. Uma campanha
que não seleciona números usa apenas números elegíveis do seu projeto, e o
projeto precisa ter pelo menos um número em um plano que inclui Campanhas. Ela
também envia por um único tipo de envio: números do WhatsApp quando algum estiver
pronto; caso contrário, números da Cloud API; caso contrário, números de teste.

| Quando | O que acontece |
| - | - |
| Você cria ou edita o rascunho | O rascunho é salvo em qualquer plano; nenhuma mensagem é enviada |
| Você altera a seleção depois do lançamento | As verificações de lançamento são executadas na nova seleção, inclusive em uma campanha agendada que ainda não começou |
| Você a lança | `402 campaigns_not_entitled` quando um número selecionado não existe ou o plano dele não inclui Campanhas, ou quando uma campanha sem seleção não tem nenhum número assim no projeto. `400 invalid_parameter` quando um número selecionado não está conectado ou a seleção mistura tipos de envio |
| Enquanto ela está em andamento | A campanha é pausada quando um número selecionado que está pronto para enviar perdeu Campanhas, ou quando nenhum número de um grupo sem seleção tem Campanhas. `campaign.paused` traz o motivo e o código `campaigns_not_entitled`. Faça o upgrade do número ou altere a seleção e depois retome |

Um número selecionado que se desconecta ou está em resfriamento enquanto a
campanha é executada fica de fora até estar pronto de novo; a campanha não é
pausada por causa dele. Se esse número também perdeu Campanhas, a campanha é
pausada assim que ele estiver pronto para enviar de novo. Se um número
selecionado for removido do projeto, ou se os números selecionados acabarem em
tipos de envio diferentes (por exemplo, depois que um número passa para a Cloud
API), a campanha é pausada e `campaign.paused` traz o código
`invalid_parameter`. Altere a seleção e depois retome.

Um número cujo plano não pode ser determinado é tratado como sem direito de uso.
A verificação falha de forma fechada.

## Limites de frequência por contato

> [!NOTE]
>
> Os limites de frequência por contato exigem que o beta seja oferecido e
> habilitado para a sua equipe. Definir um limite sem acesso retorna
> `403 feature_unavailable`.

Um limite por contato restringe as mensagens de campanha para um telefone em
todas as campanhas, projetos e números de envio da sua equipe. Ele inclui
primeiras mensagens, mensagens de sequência e acompanhamentos por confirmação.
Envios de teste e mensagens fora de campanhas não contam.

### Defina o limite da equipe no Console

1. Abra **Campanhas** e depois **Configurações**.
2. Em **Limite de frequência por contato**, participe do beta se a sua equipe
   ainda não participou.
3. Informe um limite para **Por contato, 24 horas móveis**, **Por contato, 7 dias móveis** ou para os dois. Deixe um campo vazio para não ter limite nessa janela.
4. Selecione **Salvar**.

Selecione **Remover limites** para apagar as duas janelas. A remoção funciona
mesmo quando o beta não está disponível para a sua equipe. Se outra pessoa salvou
o limite depois que você abriu a página, o Console pede que você carregue as
configurações mais recentes antes de salvar de novo. Membros da equipe que não
são proprietários nem administradores veem o limite salvo, mas não podem
alterá-lo.

### Defina um limite de campanha no Console

Uma campanha pode ter o seu próprio limite. Em cada janela vale o menor entre o
limite da campanha e o limite da equipe, então um limite de campanha só pode
deixar o envio mais restrito.

1. No builder de campanhas, abra a etapa **Agendamento**.
2. Em **Limite de frequência desta campanha**, informe um ou os dois limites. O
   limite da equipe aparece ao lado deles.
3. O rascunho é salvo automaticamente. A etapa **Revisão** lista o limite antes
   do lançamento.

Em uma campanha lançada, a página da campanha mostra o limite dela. Você só pode
alterá-lo ou removê-lo enquanto a campanha for um rascunho ou estiver pausada.
Pause primeiro uma campanha em andamento. Selecione **Remover limite** para
voltar a usar apenas o limite da equipe.

Se a sua equipe perder o acesso ao beta, uma campanha com limite próprio não pode
ser lançada nem retomada até você remover o limite ou o acesso voltar.

### Defina o limite da equipe pela API

Leia ou substitua o limite da equipe com
[`GET /platform/campaign-settings/frequency-cap`](/api-reference/platform/campaign-settings/get-campaign-frequency-cap)
e
[`PUT /platform/campaign-settings/frequency-cap`](/api-reference/platform/campaign-settings/update-campaign-frequency-cap).
Use uma chave de API da equipe com `campaigns:read` ou `campaigns:manage`,
respectivamente. Tokens de projeto não podem gerenciar configurações da equipe.
Proprietários e administradores da equipe conectados podem alterar as
configurações.

| Campo | Valor aceito | Significado |
| - | - | - |
| `maxPer24Hours` | Inteiro de 1 a 50, ou `null` | Máximo de mensagens para um telefone nas últimas 24 horas móveis |
| `maxPer7Days` | Inteiro de 1 a 200, ou `null` | Máximo de mensagens para um telefone nos últimos 7 dias móveis |
| `revision` | Revisão da leitura mais recente | Impede sobrescrever outra edição; um valor desatualizado retorna `409` |

Envie os dois campos de limite ao substituir as configurações. Os dois como
`null` removem o limite da equipe. Quando os dois estão definidos, o limite de 24
horas não pode ser maior que o limite de 7 dias. Uma equipe que nunca salvou
configurações tem os dois limites `null` e a revisão `0`.

O `frequencyCap` opcional de uma campanha usa os mesmos campos de limite. Em cada
janela vale o menor entre o limite dela e o limite da equipe. Um limite de
campanha só pode deixar o envio mais restrito. Altere-o enquanto a campanha for
um rascunho ou estiver pausada; uma campanha em andamento retorna `409`.
Removê-lo mantém o limite da equipe em vigor.

A verificação reserva capacidade de forma atômica antes do envio. Contam os
claims ativos, os envios bem-sucedidos e os envios com resultado incerto; claims
que falharam, foram liberados ou adiados não contam. As mensagens acima do limite
são ignoradas com `frequency_cap_exceeded`. Para primeiras mensagens ignoradas, o log de destinatários e a exportação CSV mostram
`failureReason: frequency_cap`. Filtre-as com
`status=skipped&reason=frequency_cap`.
Em uma mensagem de sequência posterior, o destinatário mantém o status do
primeiro envio e o restante da sequência dele é interrompido. Um acompanhamento
por confirmação barrado pelo limite é cancelado com esse motivo. Alterar um
limite nunca tenta novamente mensagens já ignoradas.

As análises da campanha informam `frequencyCap.skippedRecipientCount`, contando
uma vez cada destinatário com uma mensagem barrada pelo limite. No Console, a
página **Análises** da campanha mostra esse número como **Ignoradas pelo limite de frequência**. Os Logs mostram `campaign.frequency_cap.skipped`.
O evento `campaign.recipient_skipped` traz o motivo e `messageIndex`; um
acompanhamento por confirmação também traz `followUpId`.

Se o acesso ao beta for retirado ou não puder ser verificado, as campanhas que
usam um limite salvo da equipe ou da campanha são pausadas antes do próximo
despacho. Os limites salvos continuam legíveis e removíveis. Para enviar sem o
beta, remova os dois limites aplicáveis e retome. As verificações normais de
remetente, opt-out, saldo e segurança continuam valendo.

## Limites de vazão

`senderConfig.throughput` define o ritmo da campanha. Um valor acima do limite é
recusado com `400 campaign_throughput_capped`, que indica o campo. Os limites por
número são verificados quando você salva o rascunho e de novo no lançamento. O
limite de taxa depende dos planos dos números selecionados, então é verificado
no lançamento:

| Campo | Padrão | Limite |
| - | -: | - |
| `ratePerMinute` | 20 | No máximo 6.000, a vazão do plano Pro |
| `perNumberHourlyCap` | 60 | No máximo 300 |
| `perNumberDailyCap` | 500 | No máximo 2.000 |
| `jitterMinMs` | 800 | No mínimo 800 |
| `jitterMaxMs` | 3.500 | Acima de `jitterMinMs` |
| `ackTimeoutMs` | 5.000 | — |
| `coldSendPolicy` | `hold` | `hold` ou `allow` |

Uma campanha que já está em andamento é reduzida ao limite em vez de ser
encerrada, então uma alteração no meio do envio deixa a campanha mais lenta em
vez de interrompê-la. Os limites são por número, não por campanha: duas campanhas
que compartilham um número compartilham os limites dele. Enquanto um número tem o
ritmo reduzido por uma restrição, a campanha envia na menor taxa entre a sua
própria e a taxa reduzida, listada em
[Restrições](/guides/safety/enforcement#pacing-rates).

### Predefinições de intervalo

Uma campanha envia uma mensagem de cada vez. Depois de cada mensagem, ela espera
`60000 / ratePerMinute` milissegundos mais um atraso aleatório entre
`jitterMinMs` e `jitterMaxMs`. As predefinições de intervalo do console definem
esses campos; envie os mesmos valores em `senderConfig.throughput` para dar o
mesmo ritmo a uma campanha criada pela API:

| Predefinição | `ratePerMinute` | `jitterMinMs` | `jitterMaxMs` | Intervalo entre mensagens |
| - | -: | -: | -: | - |
| Rápido | 60 | 800 | 4.000 | De 1,8 a 5 segundos |
| Constante | 12 | 800 | 10.000 | De 5,8 a 15 segundos |
| Cuidadoso | 4 | 800 | 30.000 | De 15,8 a 45 segundos |
| Lento | 1 | 800 | 60.000 | De 1 a 2 minutos |
| Muito lento | 0,5 | 800 | 180.000 | De 2 a 5 minutos |

Os limites por número e o limite de taxa dos planos dos números selecionados
continuam valendo além da predefinição. Uma predefinição com taxa acima desse
limite é recusada no lançamento com `400 campaign_throughput_capped`.

## Todo envio de campanha tem digitação e ritmo

Um envio que vem de uma campanha sempre usa pelo menos um indicador de digitação
antes de cada mensagem de texto e um ritmo com variação aleatória, quaisquer que
sejam as configurações de Safe Mode do número. Uma campanha nunca aumenta as
configurações de presença ou de confirmação de leitura do número, porque elas
ficam visíveis para os seus contatos de um jeito que a digitação e o ritmo não
ficam.

A pausa de um envio é limitada pelo próprio intervalo da campanha entre
destinatários, então o ritmo nunca reduz a vazão que você configurou. Consulte
[Safe Mode](/guides/safety/safe-mode).

## Números com opt-out nunca recebem mensagens

Uma campanha verifica a [lista de opt-outs](/pt-br/guides/campaigns/opt-outs) da
sua equipe duas vezes. Quando a campanha é lançada, todo destinatário que está na
lista é marcado como `skipped` com `failureReason` `opted_out` e contado uma vez
em `skippedCount`. No momento do envio, um número que está na lista nunca é
reservado para envio, então um número adicionado à lista depois do lançamento da
campanha também fica suprimido, e colocar de novo na fila um destinatário
ignorado não envia para ele.

## Destinatários que nunca escreveram primeiro ficam retidos

A verificação de contato é feita por destinatário, no momento do envio, no número
que está prestes a enviar. Um destinatário que nunca escreveu para esse número
fica retido em vez de receber a mensagem, e a retenção traz
`409 bansafe_cold_held`.

Duas coisas mudam o resultado:

* Defina `senderConfig.throughput.coldSendPolicy` como `allow` para enviar
  mensagens a pessoas que não escreveram primeiro. Isso aumenta o risco de
  banimento do número; o padrão é `hold`.
* Envie para pessoas que escreveram para esse número. A verificação é por
  número, então um contato que escreveu para um dos seus números continua frio
  em outro.

A retenção não é uma falha do número. É um fato sobre a lista de destinatários.
Ela vale hoje, em todos os planos que incluem Campanhas, e não depende da escada
de restrições: é a própria `coldSendPolicy` da sua campanha. Consulte
[Restrições](/guides/safety/enforcement) para ver a escada em si e como cada
degrau é suspenso.

## O que a segurança faz com um destinatário

Um envio de campanha passa pelo degrau de restrição do número, além das
verificações acima. O que acontece com o destinatário depende de qual verificação
barrou o envio:

| O que barrou o envio | O destinatário | A campanha |
| - | - | - |
| O destinatário está na lista de opt-outs da equipe | Contado uma vez em `skippedCount`, nunca tentado, com `failureReason` `opted_out` | Continua em andamento |
| O destinatário nunca escreveu para este número e `coldSendPolicy` é `hold` | Contado uma vez em `skippedCount`, nunca tentado de novo e informado por `campaign.cold_blocked` | Continua em andamento |
| O número de envio tem o ritmo reduzido por uma restrição | Colocado de novo na fila e tentado novamente depois do atraso informado, sem gastar uma tentativa de entrega e sem contar nada como falha | Continua em andamento, e `campaign.throttled` informa a passagem |
| O número de envio ou o espaço de trabalho inteiro está suspenso, o plano não inclui mais Campanhas, ou a vazão solicitada está acima do teto de segurança | Mantido na fila, com a tentativa devolvida para não gastar o limite de novas tentativas | Pausada, com `campaign.paused` trazendo o motivo e o código |
| A classificação de qualidade ou o limite de mensagens de um número oficial do WhatsApp Business caiu durante a campanha | Mantido na fila, com a tentativa devolvida para não gastar o limite de novas tentativas | Pausada, com `campaign.paused` trazendo o motivo e o código `number_quality_dropped` ou `messaging_limit_dropped` |
| O WhatsApp reteve uma mensagem de marketing porque a pessoa atingiu o limite de mensagens de marketing dela | Contado uma vez em `skippedCount`, nunca tentado de novo, com `lastError` `whatsapp_marketing_limit` | Continua em andamento, e `campaign.recipient_skipped` informa o motivo `whatsapp_marketing_limit` |

Um destinatário retido pela segurança nunca é uma falha de entrega.
`failedCount` conta os envios que o WhatsApp recusou, não os envios que a
Polymorfa nunca fez.

## Números oficiais do WhatsApp Business

Uma campanha que envia a partir de um número oficial do WhatsApp Business também
segue dois sinais do WhatsApp.

### Limite de mensagens de marketing por pessoa

O WhatsApp limita quantas mensagens de marketing uma pessoa recebe de todas as
empresas. Quando uma pessoa está nesse limite, o WhatsApp retém a mensagem e
informa o erro `131049`. O WhatsApp pede que os remetentes esperem pelo menos 24
horas antes de enviar esse modelo de novo para a pessoa, então a campanha não
tenta novamente esses destinatários:

* O destinatário é ignorado com `lastError` `whatsapp_marketing_limit`.
* `campaign.recipient_skipped` informa o motivo `whatsapp_marketing_limit`.
* O destinatário ignorado é contado uma vez em `skippedCount`, não em
  `failedCount`.

O WhatsApp pode informar isso depois de ter aceitado o envio. Um destinatário já
contado em `sentCount` passa então para `skippedCount`. O WhatsApp também pode
informar a mensagem como entregue em um dos dispositivos da pessoa e retida em
outro. A entrega prevalece: o destinatário conta como entregue e volta para
`sentCount`.

Para alcançar essas pessoas depois, envie para elas em uma nova campanha pelo
menos 24 horas depois de terem sido ignoradas.

### Qualidade do número e limite de mensagens

Uma campanha em andamento é pausada quando um número usado por ela perde
situação com o WhatsApp enquanto a campanha é executada:

| O que mudou | Código em `campaign.paused` |
| - | - |
| A classificação de qualidade do número caiu, por exemplo de verde para amarelo, ou o WhatsApp sinalizou o número | `number_quality_dropped` |
| O WhatsApp reduziu o limite de mensagens | `messaging_limit_dropped` |

A Polymorfa compara cada número com a situação que ele tinha quando a campanha
começou a enviar por ele. Um número que já estava amarelo no lançamento pode
executar uma campanha; ele só é pausado se cair mais. A classificação é
verificada no máximo a cada cinco minutos enquanto a campanha envia, então uma
queda pode levar até cinco minutos para pausar a campanha. Assim que a Polymorfa
detecta a queda, a campanha não envia mais nada a partir desse número até você
retomá-la.

Revise a qualidade do número no WhatsApp Manager e depois retome ou encerre a
campanha. Uma campanha retomada continua a partir da situação atual do número e
só é pausada de novo se ela cair mais.

## Encerrar e excluir

Encerrar sempre significa cancelar. Encerrar passa uma campanha em rascunho, em
andamento ou pausada para `cancelling` e depois para `cancelled` quando os envios
já em curso terminam, e os destinatários que ainda não receberam o envio não o
recebem. Encerrar nunca é bloqueado por uma suspensão do espaço de trabalho nem
pela perda do direito de uso do plano, então uma campanha pausada por uma
verificação sempre pode ser encerrada.

Excluir remove uma campanha `draft`, `completed`, `failed`, `cancelled` ou
`archived`. Uma campanha que ainda está ativa, incluindo um rascunho com
lançamento agendado, é recusada com `409 state_conflict`: encerre-a primeiro e
depois exclua. Se uma campanha concluída ou com falha ainda tiver um evento final
para entregar, excluir ou arquivar retorna `409 state_conflict`. Tente novamente
depois que esse evento for entregue.

## Um número novo aumenta o volume aos poucos

O limite diário de um número começa baixo e sobe até o `perNumberDailyCap` da
campanha ao longo de `warmupDays` dias, em linha reta. Com os padrões
(`warmupDailyStart` 20, `perNumberDailyCap` 500, `warmupDays` 14), o teto de cada
dia é:

| Dia | Limite diário | Dia | Limite diário |
| -: | -: | -: | -: |
| 0 | 20 | 7 | 260 |
| 1 | 54 | 8 | 294 |
| 2 | 88 | 9 | 328 |
| 3 | 122 | 10 | 362 |
| 4 | 157 | 11 | 397 |
| 5 | 191 | 12 | 431 |
| 6 | 225 | 13 | 465 |
| | | 14 em diante | 500 |

Um número é tratado como novo durante os seus primeiros 14 dias, aqui e na
constatação `warmup_ignored`, que começa nas mesmas 20 mensagens por dia. O
aquecimento sozinho não mantém essa constatação fechada: verifique-a no número
enquanto uma nova campanha é executada. Consulte
[Constatações](/guides/safety/findings).

O aquecimento é ancorado na idade do número, não em quando ele executou a
primeira campanha: a Polymorfa usa o primeiro instante em que consegue comprovar
que o número estava em uso, como quando o número foi vinculado ou a mensagem mais
antiga que o histórico dele contém. A âncora só se move para trás, então um
número que já está aquecido não pode voltar para o aquecimento. Um número cuja
idade não pode ser determinada é tratado como aquecido e envia com o limite
completo.

Enquanto um número está em aquecimento, os destinatários além do limite do dia
não são descartados. Eles continuam na fila para a próxima janela, e
`campaign.cap_reached` informa o número, o limite e quando a janela é
reiniciada.

O WhatsApp também pode limitar quantas conversas novas um número de dispositivo
vinculado inicia em um ciclo. Quando o WhatsApp limita um número, o número sai do
grupo até o ciclo reiniciar, e `campaign.cap_reached` informa `capType`
`new_chat`. Consulte
[Limite de conversas novas do WhatsApp](/pt-br/guides/numbers/new-chat-cap).


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