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

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.

Ver em Markdown

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:

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

JSON
{
  "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"
    }
  }
}
CampoSignificado
enabledtrue 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.
pacingtrue quando a Polymorfa está segurando os envios de novas conversas deste número enquanto ele está no limite. Só é true quando enabled é true.
statusO último status informado pelo WhatsApp, ou null antes de o WhatsApp informar algum.
cappedtrue 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, remainingNovas conversas permitidas no ciclo, iniciadas no ciclo e restantes, conforme informado pelo WhatsApp.
cycleStartsAt, resetsAtO 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.
observedAtQuando 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_reached informa o número com capType new_chat, o limite informado pelo WhatsApp em capLimit e o fim do ciclo em windowResetsAt. 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.throttled informa reason new_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.