Números: qualidade e limite de envio

O número que envia mensagens é o ativo mais frágil da operação. Se a Meta restringe ou bane o número, os envios param até a situação ser resolvida com a Meta. Esta página explica o que a Meta mede em cada número, como subir o volume sem perder qualidade e como acompanhar tudo pela API.

O que é a qualidade do número

A Meta mantém dois indicadores por número:

Quality rating (qualityScore): a saúde do número, calculada pela Meta com base nos sinais dos destinatários, como bloqueios e denúncias.
Limite de envio (messagingTier): o teto operacional, quantos destinatários únicos o número alcança com conversas iniciadas pela empresa em 24h.

Qualidade baixa pode levar a Meta a restringir o número.

`qualityScore`	Na Meta	O que fazer
`HIGH`	Verde	Manter o padrão de envio
`MEDIUM`	Amarelo	Revisar conteúdo e frequência antes de aumentar o volume
`LOW`	Vermelho	Reduzir o volume, pausar marketing, revisar a base
`FLAGGED`	Sinalizado	Parar marketing e revisar o conteúdo recente
`UNKNOWN`		A Arara ainda não recebeu o valor. Não trate como “tudo certo”

Limite de envio

`messagingTier`	Tier informado pela Meta (destinatários únicos / 24h)	Teto diário que a Arara aplica
`TIER_50`	50	50
`TIER_250`	250	250
`TIER_1K`	1.000	1.000
`TIER_2K`	2.000	1.000
`TIER_10K`	10.000	10.000
`TIER_100K`	100.000	100.000
`UNLIMITED`	Sem limite	Sem limite
`UNKNOWN`	Ainda não sincronizado	1.000

messagingTier é o valor que a Meta informa. No envio, a Arara trata TIER_2K e UNKNOWN como 1.000 por dia. Quem sobe ou desce o limite é a Meta, com critérios próprios que mudam com o tempo. Consulte a documentação da Meta para a regra vigente. A Arara atualiza qualidade e limite de duas formas: consultando o provedor a cada 6 horas e recebendo os eventos de conta que a Meta envia.

Como subir de tier: aquecimento

Número recém-verificado que sai enviando o limite inteiro tende a perder qualidade. Crescer devagar é o que permite à Meta subir o limite. A Arara calcula uma recomendação de ritmo diário por número:

curl https://api.ararahq.com/v1/organizations/me/numbers/{id}/warming \
  -H "Authorization: Bearer $ARARA_API_KEY"

{
  "numberId": "4b1f0c7e-2a3d-4e59-9a61-0f2d5c8b7a10",
  "qualityScore": "HIGH",
  "messagingTier": "TIER_1K",
  "daysSinceVerified": 10,
  "dailyCapByTier": 1000,
  "recommendedDailySends": 500,
  "recommendedPacePct": 50,
  "currentDailyAverage": 312,
  "recommendation": "Days 8-14. Ramp to 50% of cap. Keep template diversity high."
}

Como a recomendação é calculada:

Situação do número	Ritmo recomendado
Ainda não verificado pela Meta	0% (aguarde a verificação)
`FLAGGED`	0% (pause marketing e revise o conteúdo recente)
`LOW`	30% do limite, só UTILITY, sem MARKETING por 7 dias
Dias 1 a 7 após verificação	20% do limite
Dias 8 a 14	50% do limite
Dias 15 a 30	80% do limite
Depois de 30 dias, ou `UNLIMITED`	100%

A recomendação é orientativa: a API não trava envio por ela. Programe o seu envio para respeitar recommendedDailySends.

Para datas de pico, como Black Friday, comece a aquecer o número semanas antes. O limite de envio não sobe no dia.

O que derruba a qualidade

A Meta não publica pesos, mas os sinais conhecidos são:

Sinal	Como evitar
Destinatário bloqueia o número	Opt-in real e conteúdo que a pessoa espera
Destinatário denuncia como spam	Tom apropriado, sem urgência forçada
Destinatário para de receber marketing da marca	Frequência controlada
Vários marketing seguidos para o mesmo contato	Espaçar as campanhas para a mesma base

Os três cenários mais comuns de queda:

Envio agressivo de marketing

Template MARKETING recém-aprovado enviado para a base inteira, incluindo contatos inativos ou que não consentiram. O que fazer: pause marketing por alguns dias e mantenha só UTILITY com notificações reais.

Conteúdo que gera bloqueio

Texto em caixa alta, “URGENTE”, “ÚLTIMA CHANCE”, promessa exagerada, cobrança ameaçadora. O que fazer: revise o texto seguindo a Política de templates. Tom conversacional bloqueia menos.

Falta de opt-in real

Base importada do CRM sem consentimento para WhatsApp. A pessoa recebe sem esperar e bloqueia. O que fazer: pare de enviar para essa base e reconquiste o consentimento por outro canal. Veja Compliance.

Consultar pela API

Tipos de número

Número próprio conectado

Você conecta um número seu à organização pelo fluxo de cadastro da Meta no Dashboard. Não ocupa mensalidade de número.

Número provisionado pela Arara

A Arara providencia a linha para você. Depende do plano e tem mensalidade própria. Veja Preços e limites.

Na API, os dois aparecem com type: "DEDICATED". O campo provisionedByArara diz qual é qual.

Campanhas exigem número conectado. Sem nenhum número dedicado ativo na organização, POST /v1/campaigns responde 403 com error.code = "NO_DEDICATED_NUMBER".

Listar números

curl https://api.ararahq.com/v1/organizations/me/numbers \
  -H "Authorization: Bearer $ARARA_API_KEY"

Retorna:

{
  "numbers": [
    {
      "id": "4b1f0c7e-2a3d-4e59-9a61-0f2d5c8b7a10",
      "name": "Atendimento",
      "alias": null,
      "description": null,
      "phoneNumber": "+5511999999999",
      "type": "DEDICATED",
      "isDefault": true,
      "status": "ACTIVE",
      "qualityScore": "HIGH",
      "messagingTier": "TIER_1K",
      "verifiedAt": "2026-08-20T13:00:00Z",
      "lastHealthCheckAt": "2026-09-15T06:00:00Z",
      "provider": "GUPSHUP",
      "createdAt": "2026-08-20T12:40:00Z",
      "messagesLast7d": 1840,
      "messagesLast30d": 7215,
      "deliveredLast30d": 7033,
      "provisionedByArara": false,
      "wabaId": "a0e5d2f4-7b8c-4d1e-9f3a-6c2b1d0e9f87",
      "isCoexistence": false
    }
  ],
  "slot": {
    "used": 1,
    "max": 1,
    "planLabel": "VOO",
    "atCap": true,
    "noEntitlement": false,
    "monthlyPriceCents": 0,
    "monthlyTotalCents": 0
  }
}

status é o estado do número na Arara: ACTIVE, PENDING_REVIEW, SUSPENDED ou DISABLED.
slot resume quantos números o plano permite (max = -1 significa sem limite), se a organização já está no teto e, em centavos, a mensalidade por número provisionado pela Arara (monthlyPriceCents) e o total mensal dos números ativos (monthlyTotalCents). Os valores do exemplo são ilustrativos.
isCoexistence indica número que segue ativo no app WhatsApp Business junto com a API. null enquanto não sincronizou.

Cada organização pode ter mais de um número, por exemplo um para marketing e outro para atendimento, para não concentrar o risco em uma linha só. Cada número tem qualidade e limite próprios. O número de cada envio é escolhido no campo sender de POST /v1/messages. Sem ele, o envio sai pelo número padrão (isDefault). Quantos números a organização pode ter depende do plano: veja slot.max na resposta acima. Outras operações no mesmo recurso:

Método e rota	O que faz
`PATCH /v1/organizations/me/numbers/{id}`	Atualiza `name`, `alias`, `description` e `isDefault`
`DELETE /v1/organizations/me/numbers/{id}`	Desativa o número. Número padrão com outros ativos responde `409 DEFAULT_NUMBER_CANNOT_BE_DELETED`
`GET /v1/organizations/me/numbers/requests`	Lista pedidos de número novo e o status de cada um
`GET /v1/organizations/me/numbers/reactivatable`	Números suspensos por cobrança que podem ser religados
`POST /v1/organizations/me/numbers/{id}/reactivate`	Religa um número suspenso por cobrança

GET nessas rotas funciona com chave de leitura. POST, PATCH e DELETE exigem chave com permissão ADMIN.

Pedir um número novo

Pelo Dashboard em Números, ou via API:

curl -X POST https://api.ararahq.com/v1/organizations/me/numbers/request \
  -H "Authorization: Bearer $ARARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "areaCode": "11",
    "displayName": "Minha Marca",
    "reason": "Número exclusivo para campanhas",
    "expectedVolume": "50 mil mensagens por mês"
  }'

Todos os campos são opcionais: areaCode, displayName, profilePictureUrl, reason e expectedVolume (texto livre). Resposta 202:

{
  "status": "received",
  "requestId": "9d2e6f1a-3b4c-4a5d-8e7f-1a2b3c4d5e6f",
  "message": "Pedido recebido. A gente te chama em até 1 dia útil pra liberar."
}

O provisionamento não é automático: a operação da Arara entra em contato para concluir. Erros possíveis:

402 PLAN_REQUIRED quando o plano não inclui número provisionado pela Arara.
409 PLAN_SLOT_EXHAUSTED quando a organização já está no teto de números do plano.

Eventos de webhook

Quando a Meta muda algo no número ou na conta, a Arara envia eventos para o webhook da organização:

Evento	Quando dispara	`data`
`number.status`	Número banido, restrito, reativado, ou erro no cadastro	`status` (`BANNED`, `RESTRICTED`, `ACTIVE`, `ONBOARDING_ERROR`), `reason` ou `restriction`, `phone`
`number.tier_updated`	Mudança de limite de envio, ou número sinalizado / dessinalizado	`event`, `tier`
`number.name_status`	Decisão da Meta sobre o nome de exibição	`decision`, `reason`
`account.review`	Resultado da revisão da conta WhatsApp	`decision`
`account.capability`	Mudança nos limites da conta	`maxDailyConversationPerPhone`, `maxPhoneNumbersPerBusiness`
`template.quality_updated`	A Meta mudou a qualidade de um template	`name`, `quality`
`template.updated`	Status do template mudou, inclusive para pausado

Mudança de qualityScore detectada na consulta periódica atualiza o número na API e no Dashboard, mas não gera evento de webhook. Para automação baseada em qualidade, consulte GET /v1/organizations/me/numbers periodicamente.

Perfil do negócio

Nome de exibição, descrição, vertical, e-mail, sites e foto ficam em /v1/organizations/me/business-profile:

# Consultar
curl https://api.ararahq.com/v1/organizations/me/business-profile \
  -H "Authorization: Bearer $ARARA_API_KEY"

# Enviar o perfil salvo para a Meta
curl -X POST https://api.ararahq.com/v1/organizations/me/business-profile/sync \
  -H "Authorization: Bearer $ARARA_API_KEY"

O resultado do envio fica em metaSyncStatus, metaSyncedAt e metaSyncError. A propagação nos aparelhos dos clientes depende da Meta.

Próximos passos

Webhooks

Assinatura, retentativas e todos os eventos.

Templates

Como não derrubar a qualidade com template ruim.

Preços e limites

Quantos números cada plano permite.

Compliance

Opt-in e consentimento.

Início

Conceitos

O que é a qualidade do número

Limite de envio

Como subir de tier: aquecimento

O que derruba a qualidade

Consultar pela API

Tipos de número

Número próprio conectado

Número provisionado pela Arara

Listar números

Pedir um número novo

Eventos de webhook

Perfil do negócio

Próximos passos

Webhooks

Templates

Preços e limites

Compliance

​O que é a qualidade do número

​Limite de envio

​Como subir de tier: aquecimento

​O que derruba a qualidade

​Consultar pela API

​Tipos de número

Número próprio conectado

Número provisionado pela Arara

​Listar números

​Pedir um número novo

​Eventos de webhook

​Perfil do negócio

​Próximos passos

Webhooks

Templates

Preços e limites

Compliance

O que é a qualidade do número

Limite de envio

Como subir de tier: aquecimento

O que derruba a qualidade

Consultar pela API

Tipos de número

Listar números

Pedir um número novo

Eventos de webhook

Perfil do negócio

Próximos passos