> ## Documentation Index > Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt > Use this file to discover all available pages before exploring further. # Números: qualidade e limite de envio > O que são o quality rating e o limite de envio do número WhatsApp, como subir o volume sem perder qualidade e como consultar tudo pela API. 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: ```bash theme={null} curl https://api.ararahq.com/v1/organizations/me/numbers/{id}/warming \ -H "Authorization: Bearer $ARARA_API_KEY" ``` ```json theme={null} { "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: 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. 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](/templates/policy). Tom conversacional bloqueia menos. 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](/concepts/compliance). ## Consultar pela API ### Tipos de número Você conecta um número seu à organização pelo fluxo de cadastro da Meta no [Dashboard](https://app.ararahq.com). Não ocupa mensalidade de número. A Arara providencia a linha para você. Depende do plano e tem mensalidade própria. Veja [Preços e limites](/concepts/pricing). 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 ```bash theme={null} curl https://api.ararahq.com/v1/organizations/me/numbers \ -H "Authorization: Bearer $ARARA_API_KEY" ``` Retorna: ```json theme={null} { "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: ```bash theme={null} 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`: ```json theme={null} { "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](/webhooks): | 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`: ```bash theme={null} # 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 Assinatura, retentativas e todos os eventos. Como não derrubar a qualidade com template ruim. Quantos números cada plano permite. Opt-in e consentimento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.