API oficial

WABA e portfólio: a estrutura da Meta que decide se o seu disparo vai sair

Por VeyloCRM · · 14 min de leitura

Quase todo problema estranho na API oficial — template que existe mas não é encontrado, imagem que funciona em um número e falha em outro, fila que trava com tudo verde — tem a mesma origem: uma confusão entre as camadas da estrutura da Meta. Elas são três, cada uma guarda coisas diferentes, e o que pertence a uma não atravessa para a outra. Entender esse desenho é o que separa uma operação previsível de uma sequência de surpresas no meio do disparo.

As três camadas

A estrutura da Meta para mensagens empresariais tem três níveis encaixados, e cada um responde por coisas diferentes:

A regra que explica quase todos os problemas: cada coisa pertence a uma camada específica e não é herdada pelas outras. Template pertence à conta comercial. Qualidade pertence ao número. Pagamento pertence ao portfólio. Quem trata as três como se fossem "a conta do WhatsApp da empresa" acaba surpreendido.

Portfólio: onde mora a empresa

O portfólio é o que a Meta entende como sendo a organização. Nele ficam:

Esse último item merece atenção porque é o mais pesado: uma restrição aplicada ao portfólio alcança tudo que está dentro dele. Não adianta trocar de número nem criar outra conta comercial ali dentro — o bloqueio é da camada de cima.

A conta comercial do WhatsApp

A conta comercial é a camada de trabalho do dia a dia. É ela que guarda:

A frase que vale memorizar é esta: template é aprovado por conta comercial. Um modelo criado na conta A não existe para um número que está na conta B. É a explicação de longe mais comum para "o template estava aprovado e mesmo assim o disparo falhou".

Leitura liberada

Continue lendo de graça

Preencha uma vez e libere este e todos os outros artigos do blog. Não cobramos nada — só queremos saber para quem estamos escrevendo.

Leva 20 segundos. Prefere falar direto no WhatsApp?

O número e o que é dele

O número é a camada mais concreta e a que o cliente enxerga. Pertencem a ele:

  • O nome de exibição, que passa por aprovação e precisa corresponder à empresa.
  • A foto e o perfil comercial.
  • A classificação de qualidade, calculada a partir de bloqueios e denúncias.
  • O limite de conversas iniciadas, que sobe com volume e qualidade.
  • O identificador técnico, usado em cada chamada de envio.

Esse identificador guarda uma armadilha silenciosa: ele muda quando o número é desconectado e conectado de novo. Sistemas que arquivam conversas por esse identificador em vez de pelo telefone acabam com o histórico órfão depois de uma reconexão — as conversas continuam no banco, mas ninguém as encontra. Quem constrói integração precisa casar histórico pelo telefone, nunca pelo identificador da conexão.

O que não atravessa de uma conta para outra

A lista de coisas que ficam presas à conta comercial explica a maior parte dos incidentes:

  • Templates. Precisam ser submetidos e aprovados em cada conta que vai usá-los.
  • Arquivos enviados à plataforma. O identificador de uma imagem pertence ao número que a enviou; reaproveitá-lo em outro número falha.
  • Limite e qualidade. Um número maduro não empresta reputação a um número novo da mesma conta.
  • A janela de atendimento. Ela é entre o cliente e um número específico. Responder por outro número não usa a janela aberta pelo primeiro.

É por isso que rodízio de números exige preparo. Distribuir o disparo entre três números só funciona se os três tiverem o template aprovado, a mídia enviada e cota disponível. Faltando qualquer um desses itens em um deles, a fila para quando chegar a vez dele — e o sintoma é uma falha em massa no meio do envio, que parece bloqueio e não é.

Uma conta ou várias?

A pergunta aparece assim que a empresa passa de um número. A resposta depende de três critérios.

Junte na mesma conta quando os números pertencem à mesma marca, usam os mesmos templates e atendem ao mesmo público. Uma conta só significa uma biblioteca de templates para manter, uma assinatura de eventos e menos configuração duplicada.

Separe em contas diferentes quando existem marcas distintas com nomes de exibição próprios, quando o conteúdo é muito diferente — uma operação de cobrança e uma de vendas não deveriam compartilhar reputação —, ou quando cada unidade precisa de faturamento e responsáveis próprios.

Um cuidado sobre o isolamento: separar contas não protege contra tudo. Restrição no nível do portfólio alcança todas as contas dentro dele. A separação isola template, limite e boa parte das restrições operacionais — não integridade da organização.

Cobrança: a falha mais silenciosa

Este é o problema que mais consome horas de investigação técnica sem ser técnico.

Cada conta comercial precisa de um meio de pagamento válido associado. Quando existe fatura em aberto, os envios podem ser barrados mesmo com o número em qualidade verde, template aprovado e cota disponível. E a falha devolvida não diz "há uma fatura pendente" — ela vem genérica.

O cenário clássico é uma empresa com vários números distribuídos em contas comerciais diferentes: uma delas tem pendência e as outras não. O disparo funciona normalmente até o rodízio chegar naquele número, e aí trava. Do lado de fora, parece defeito intermitente do sistema.

A conclusão prática: antes de investigar código, conferir a situação financeira de cada conta comercial. É uma verificação de dois minutos que economiza um dia.

Verificação da empresa e o que ela libera

A verificação acontece no portfólio e é a Meta conferindo documentos para confirmar que a organização existe e que quem a administra tem relação com ela. Ela costuma exigir documento de constituição, comprovante de endereço e alguma forma de presença pública verificável.

Sem verificação, a operação funciona em modo limitado: menos números permitidos, teto de conversas mais baixo e restrições em alguns recursos. Com verificação, os limites se abrem conforme o uso.

Dois pontos que economizam retrabalho. Primeiro: o nome de exibição do número precisa ter relação clara com a empresa verificada — nome de fantasia sem vínculo é a causa mais comum de recusa nessa etapa. Segundo: a verificação é do portfólio, então vale para todas as contas comerciais dentro dele, o que é um bom argumento para não espalhar operações por portfólios diferentes sem necessidade.

Conectar o número de um cliente

Para quem presta serviço, existe um roteiro que evita descobrir problema no dia do disparo:

  • O número precisa estar livre. Um telefone já conectado ao aplicativo comum precisa ser desvinculado antes, e essa migração apaga o histórico local do aparelho — o cliente precisa saber disso antes, não depois.
  • O portfólio é do cliente. A empresa que presta serviço recebe acesso; ela não deve ser dona dos ativos do cliente. Isso evita disputa depois e protege os dois lados.
  • Verificação antes do volume. Começar o processo cedo, porque ele não é instantâneo.
  • Templates aprovados antes da campanha. Análise leva tempo e a primeira submissão costuma precisar de ajuste.
  • Meio de pagamento configurado e testado com um envio real, não apenas cadastrado.
  • Aquecimento. Número novo tem limite baixo. Subir volume gradualmente é o que constrói qualidade em vez de queimá-la na primeira semana.

Quem pode fazer o quê

Permissão é a parte da estrutura que mais gera bloqueio inexplicável, porque o erro devolvido raramente diz "falta permissão para esta pessoa".

Os papéis se distribuem por camada. No portfólio existem administradores, que mexem em tudo, inclusive em pagamento e verificação, e funcionários, com acesso apenas aos ativos que lhes forem concedidos. Em cada ativo — a conta comercial do WhatsApp, uma Página, uma conta do Instagram — a permissão é atribuída separadamente, e ter acesso ao portfólio não significa ter acesso a tudo que está dentro dele.

Três situações concentram os problemas:

  • A pessoa que criou tudo saiu da empresa. Se ela era a única administradora do portfólio, a organização perde o controle dos próprios ativos, e recuperar isso é um processo demorado com a Meta. A regra é ter sempre no mínimo dois administradores, e que ao menos um seja um cargo estável.
  • O sistema integrado não tem permissão sobre aquele ativo. A empresa concede acesso ao portfólio e esquece de conceder ao número, e o envio falha com erro genérico de permissão.
  • Aplicativo em modo restrito. Enquanto uma integração não tem aprovação plena, ela funciona apenas para pessoas que têm papel formal no aplicativo. É o que faz um teste passar com a equipe e falhar com o primeiro cliente real — e não é defeito, é o estágio da autorização.

Vale registrar em algum lugar acessível quem é administrador de cada camada. Parece burocracia até o dia em que alguém sai e ninguém consegue aprovar um template.

Uma operação em números

Uma empresa com três números serve de exemplo do que a estrutura custa quando é montada sem plano.

Montagem improvisada: cada número foi conectado por uma pessoa diferente, em três contas comerciais separadas, dentro de dois portfólios. O template de campanha foi aprovado em uma conta só. O disparo de 9.000 contatos foi distribuído igualmente entre os três números.

  • 3.000 mensagens saíram pelo número A, que tinha o template — 96% de entrega
  • 3.000 falharam no número B por template inexistente naquela conta
  • 3.000 falharam no número C pelo mesmo motivo, mais uma fatura em aberto naquele portfólio

Resultado: 33% do disparo entregue, dois números com histórico de falha em massa e uma equipe convencida de que o problema era o sistema de envio. O custo real não foram as 6.000 mensagens perdidas — foi o dia de investigação em cima de um problema que estava inteiramente no painel da Meta.

A mesma operação com estrutura planejada — um portfólio, uma conta comercial, os três números dentro dela, template aprovado uma vez e valendo para os três, pagamento único — entrega os mesmos 9.000 sem intervenção. A diferença entre os dois cenários não é técnica nem custa dinheiro: é uma hora de organização antes de começar.

Cinco erros de estrutura

  • Assumir que template aprovado vale para todos os números. Ele vale para a conta comercial em que foi aprovado, e o rodízio esbarra nisso no meio do disparo.
  • Espalhar números por contas e portfólios sem necessidade. Multiplica biblioteca de templates, verificação e faturas — e nenhum ganho.
  • Ser dono do portfólio do cliente. Cria disputa de propriedade e responsabilidade sobre ativos que não são seus.
  • Procurar defeito técnico antes de conferir a fatura. Pendência financeira barra envio com tudo verde e devolve erro genérico.
  • Guardar histórico pelo identificador da conexão. Reconectar o número gera identificador novo e órfã as conversas; o vínculo correto é o telefone.

Os números para acompanhar

Cinco indicadores mantêm a estrutura sob controle. A cobertura de templates por número — quantos dos modelos que a operação usa existem em cada número —, que deveria ser 100% antes de qualquer disparo com rodízio. O status de verificação do portfólio, que destrava limites e costuma ser lembrado tarde demais. A situação financeira de cada conta comercial, conferida antes de campanha grande. A qualidade e o limite por número, acompanhados individualmente, porque a média esconde o número que está prestes a ser restringido. E a quantidade de contas comerciais ativas, que deveria ser o menor número que atende à operação — cada conta a mais é uma biblioteca de templates, uma configuração de eventos e uma fatura para alguém esquecer.

Perguntas frequentes

Qual a diferença entre portfólio, conta comercial e número na Meta?

São três camadas encaixadas, e cada uma guarda coisas diferentes que não são herdadas pelas outras. O portfólio comercial é a camada mais alta e representa a organização: nele ficam pessoas e permissões, a verificação da empresa, o meio de pagamento, os ativos como páginas e contas do Instagram, e o histórico de integridade — uma restrição aplicada aqui alcança tudo que está dentro. A conta comercial do WhatsApp, ou WABA, fica dentro do portfólio e é a camada de trabalho: ela guarda os templates, agrupa os números e concentra a assinatura de eventos. O número de telefone fica dentro da conta comercial e é dele o nome de exibição, a foto, a classificação de qualidade e o limite de conversas iniciadas. A regra que explica quase todos os problemas é que cada coisa pertence a uma camada específica: template é da conta, qualidade é do número, pagamento é do portfólio.

Por que meu template aprovado não funciona em outro número?

Porque template é aprovado por conta comercial, não por empresa e não por número. Um modelo criado na conta A simplesmente não existe para um número que está na conta B, e essa é de longe a explicação mais comum para "o template estava aprovado e mesmo assim o disparo falhou". O mesmo vale para arquivos: o identificador de uma imagem enviada à plataforma pertence ao número que a enviou, e reaproveitá-lo em outro número falha. Limite e qualidade também não atravessam — um número maduro não empresta reputação a um número novo da mesma conta. E a janela de atendimento é entre o cliente e um número específico, então responder por outro número não aproveita a janela aberta pelo primeiro. Por isso rodízio de números exige preparo: os três precisam ter o template aprovado, a mídia enviada e cota disponível, ou a fila para quando chegar a vez do que está faltando.

Devo usar uma conta comercial só ou várias?

Junte na mesma conta quando os números pertencem à mesma marca, usam os mesmos templates e atendem ao mesmo público — uma conta só significa uma biblioteca de templates para manter, uma assinatura de eventos e menos configuração duplicada. Separe em contas diferentes quando existem marcas distintas com nomes de exibição próprios, quando o conteúdo é muito diferente, já que uma operação de cobrança e uma de vendas não deveriam compartilhar reputação, ou quando cada unidade precisa de faturamento e responsáveis próprios. Um cuidado importante sobre o isolamento: separar contas não protege contra tudo. Restrição no nível do portfólio alcança todas as contas dentro dele. A separação isola template, limite e boa parte das restrições operacionais, mas não a integridade da organização.

O disparo trava com o número verde e o template aprovado. Por quê?

A causa mais frequente e mais silenciosa é financeira. Cada conta comercial precisa de um meio de pagamento válido associado, e quando existe fatura em aberto os envios podem ser barrados mesmo com qualidade verde, template aprovado e cota disponível — sendo que a falha devolvida não diz "há uma fatura pendente", ela vem genérica. O cenário clássico é uma empresa com vários números distribuídos em contas comerciais diferentes, uma delas com pendência e as outras não: o disparo funciona normalmente até o rodízio chegar naquele número e então trava, o que de fora parece defeito intermitente do sistema. A conclusão prática é direta: antes de investigar código, conferir a situação financeira de cada conta comercial. É uma verificação de dois minutos que economiza um dia inteiro.

O que conferir antes de conectar o número de um cliente?

Seis pontos evitam descobrir problema no dia do disparo. O número precisa estar livre — telefone já conectado ao aplicativo comum precisa ser desvinculado, e essa migração apaga o histórico local do aparelho, algo que o cliente precisa saber antes e não depois. O portfólio deve ser do cliente, com a empresa prestadora recebendo acesso em vez de virar dona dos ativos, o que evita disputa e protege os dois lados. A verificação da empresa deve começar cedo, porque não é instantânea e é ela que destrava limites. Os templates precisam estar aprovados antes da campanha, já que a análise leva tempo e a primeira submissão costuma precisar de ajuste. O meio de pagamento precisa estar configurado e testado com um envio real, não apenas cadastrado. E o número novo precisa de aquecimento: começar com volume baixo e subir gradualmente é o que constrói qualidade em vez de queimá-la na primeira semana.

Estrutura organizada é disparo que não trava no meio

O VeyloCRM mostra quais templates existem em cada número antes de o disparo começar, avisa quando um número não tem o modelo escolhido em vez de falhar no meio da fila, casa o histórico das conversas pelo telefone e não pelo identificador da conexão, e mantém WhatsApp, Instagram e Messenger no mesmo painel — com a operação inteira em um lugar só.