Limite de novas conversas do WhatsApp
Veja o limite de novas conversas que o WhatsApp definiu para um número de dispositivo vinculado e como a Polymorfa controla o ritmo dos envios dele.
O WhatsApp pode limitar quantas novas conversas um número de dispositivo vinculado inicia em um ciclo. O WhatsApp decide isso por número. A maioria dos números não tem limite. Quando o WhatsApp não ativou um limite para um número, a Polymorfa não muda nada na forma como esse número envia.
Quando o WhatsApp ativou um limite, a Polymorfa lê o limite do número, quantas novas conversas ele iniciou no ciclo atual e quando o ciclo é reiniciado, e segura os envios que iniciariam uma nova conversa enquanto o número está no limite. Mensagens para pessoas que já têm uma conversa com o número nunca são seguradas.
O que conta como nova conversa#
Uma nova conversa é uma conversa individual com uma pessoa que o WhatsApp ainda não trata como conversa existente do seu número. O WhatsApp trata uma conversa como existente por cerca de quatro semanas depois da última mensagem que a pessoa enviou ao seu número. Grupos, listas de transmissão, canais e o seu próprio número nunca contam.
De onde vêm os números#
Todos os valores vêm do WhatsApp:
- se um limite se aplica ao número, a partir da configuração do WhatsApp para ele;
- o limite, o uso, o status e o ciclo, que o WhatsApp informa quando o número abre uma nova conversa e sempre que os atualiza.
A Polymorfa não conta as novas conversas por conta própria e não estima um limite que o WhatsApp não informou. Até o WhatsApp informar um ciclo, o limite e o uso são null.
O WhatsApp informa um de quatro status: none, first_warning, second_warning e capped. Os avisos vêm do WhatsApp antes de o número chegar ao limite. Quando o ciclo informado termina, o status fica none até o WhatsApp informar o próximo ciclo.
Ler o limite de um número#
Get session retorna newChatCapping para um número de dispositivo vinculado:
curl https://api.polymorfa.com/platform/sessions/support-line \
-H "Authorization: Bearer $POLYMORFA_API_KEY"TypeScript:
No SDK, messaging.sessions.retrieve retorna o mesmo campo; o tipo NewChatCapping está na versão do SDK publicada depois desta mudança na API.
{
"data": {
"sessionId": "support-line",
"type": "linked_device",
"status": "CONNECTED",
"newChatCapping": {
"enabled": true,
"pacing": true,
"status": "first_warning",
"capped": false,
"limit": 50,
"used": 26,
"remaining": 24,
"cycleStartsAt": "2026-09-01T00:00:00.000Z",
"resetsAt": "2026-10-01T00:00:00.000Z",
"observedAt": "2026-09-24T10:00:01.000Z"
}
}
}| Campo | Significado |
|---|---|
enabled | true quando o WhatsApp ativou um limite para este número, false quando não ativou. null quando não é possível chegar a uma decisão com a configuração do WhatsApp para o número; nesse caso, a Polymorfa não controla o ritmo em função de um limite. |
pacing | true quando a Polymorfa está segurando os envios de novas conversas deste número enquanto ele está no limite. Só é true quando enabled é true. |
status | O último status informado pelo WhatsApp, ou null antes de o WhatsApp informar algum. |
capped | true enquanto o WhatsApp informa que o número está no limite, pacing é true e o ciclo informado (ou a retenção da Polymorfa) não terminou. Só nesse caso a Polymorfa segura os envios de novas conversas. |
limit, used, remaining | Novas conversas permitidas no ciclo, iniciadas no ciclo e restantes, conforme informado pelo WhatsApp. |
cycleStartsAt, resetsAt | O ciclo atual, quando o WhatsApp o informou. Enquanto a Polymorfa retém o número depois que o WhatsApp rejeitou uma nova conversa sem informar um ciclo, resetsAt é o fim dessa retenção. |
observedAt | Quando a Polymorfa observou este estado pela última vez. |
newChatCapping é null até a Polymorfa observar o número, e não aparece para números oficiais do WhatsApp Business nem em List sessions.
O que acontece enquanto um número está no limite#
Um envio que iniciaria uma nova conversa é recusado antes de chegar ao WhatsApp, com 429 e new_chat_limit_reached. O cabeçalho Retry-After informa os segundos até o ciclo reiniciar quando o WhatsApp informou o horário de reinício. O webhook message.failed de um envio assíncrono informa error send_failed com o mesmo code. Os envios para conversas existentes continuam.
Nas campanhas, um número no limite sai do grupo de envio até o ciclo dele reiniciar. Os destinatários não são descartados:
campaign.cap_reachedinforma o número comcapTypenew_chat, o limite informado pelo WhatsApp emcapLimite o fim do ciclo emwindowResetsAt. Quando todos os números do grupo estão no limite, os destinatários continuam na fila e são tentados de novo pelo menos a cada cinco minutos;- quando um envio é recusado porque o número chegou ao limite entre ser escolhido e enviar, o destinatário volta para a fila para outro número e
campaign.throttledinformareasonnew_chat_limit_reached.
Enquanto um número está perto do limite, as campanhas enviam mais novas conversas pelos números que usaram uma parte menor do próprio limite.
Se o próprio WhatsApp rejeitar uma nova conversa porque o número chegou ao limite, o envio falha com o mesmo código new_chat_limit_reached. Quando o WhatsApp ativou um limite para o número, a Polymorfa passa a tratá-lo como no limite até o fim do ciclo informado pelo WhatsApp, ou por uma hora quando o WhatsApp não informou o ciclo atual, e as campanhas adiam os destinatários dele como descrito acima. Quando o WhatsApp não ativou um limite para o número, o envio é uma tentativa com falha, e a campanha tenta novamente como em qualquer outra falha.