Conectar o WhatsApp oficial no HorusBI

A aba WhatsApp Oficial guarda as credenciais da conta Meta de quem vai enviar. Ela aparece em dois lugares: no cadastro do Cliente, valendo para todos os Tenants dele, e no cadastro do Tenant, para o caso de um Tenant ter conta própria.

Antes de conectar, as credenciais precisam existir. O caminho para gerá-las está em Preparar a conta Meta para o WhatsApp oficial.

Quem manda quando

Uma conexão pertence a um dono só, e o mais específico ganha:

1. Conexão do Tenant. O Tenant tem WABA, aplicativo e fatura próprios.
2. Conexão do Cliente. Vale para todos os Tenants dele que não tenham a própria.
3. Número do HorusBI. Atende quem não conectou nada.

Cada dono tem no máximo uma conexão. Conectar já troca o canal: não existe um botão separado de ativação, porque cadastrar o número é a decisão.

Conectar

O formulário pede cinco valores:

• WABA ID e Phone Number ID — identificam a conta e o número. São diferentes entre si, e trocar um pelo outro é o erro mais comum.
• App ID — identifica o aplicativo. É público, então fica guardado sem criptografia.
• Token permanente — o token do System User, com expiração Nunca.
• App Secret — confere a assinatura das mensagens recebidas.

O PIN de seis dígitos fica só com você. Quem registra o número na Cloud API é o dono da conta.

Clique em Conectar. O botão testa antes de gravar, e credencial recusada não chega ao banco: token errado salvo vira alerta que falha de madrugada sem ninguém entender por quê. Ao lado fica Só testar, para conferir uma credencial sem trocar a que está valendo.

Token e App Secret são gravados criptografados e nunca mais aparecem na tela. Na volta, os dois campos mostram ******, e deixá-los assim mantém o valor guardado.

A lista de prontidão

Com a conexão salva, a aba abre por quatro linhas que respondem se a coisa funciona de verdade.

Linha	O que responde
Enviar alertas	O canal está ativo e a Meta não está bloqueando o envio
Receber mensagens	Existe aplicativo inscrito para receber os eventos desta conta
Template dos alertas	Há um template principal escolhido
Conta na Meta	A conta não tem pendência de pagamento nem de verificação

Estar salvo e estar funcionando são coisas diferentes, e é essa distinção que a lista existe para mostrar. Dá para ter credencial perfeita e mesmo assim não receber nada, porque falta a inscrição do aplicativo, ou não enviar nada, porque o cartão da conta recusou.

Cada linha que não está resolvida traz o botão que a resolve. As três perguntas do lado da Meta saem sozinhas quando você abre a aba, então a tela nunca nasce pela metade. O botão Verificar agora repete a consulta, e serve para conferir depois de mexer em algo no painel da Meta.

Credenciais e Templates ficam recolhidos logo abaixo, e é onde se corrige o que a lista apontou.

O que o Verificar agora consulta

Consulta	O que prova	Falha comum
Leitura do número	O token envia mensagens por esse número	Número não registrado (erro 133010)
Saúde da conta	A conta pode enviar agora	Meio de pagamento recusado (141006), verificação pendente (141010)
Aplicativos inscritos	As mensagens recebidas chegam até nós	Nenhum aplicativo inscrito, ou mais de um

A consulta traz também o nome de exibição aprovado e a nota de qualidade do número. Os dois a tela busca na Meta na hora, em vez de guardar cópia: valor guardado envelhece e passa a mentir com cara de certo.

Um token que não administra a conta falha com o erro 200. Acontece quando o token foi gerado no aplicativo errado, ou quando a conta de WhatsApp não está entre os ativos do usuário do sistema.

Receber mensagens

Envio funciona assim que a conexão salva. Recebimento precisa de um passo do lado da Meta, porque é o aplicativo do dono da conta que decide para onde os eventos vão.

O botão Ligar webhook, na linha Receber mensagens, faz isso por API usando o App ID já guardado. O HorusBI inscreve o aplicativo na nossa URL e inscreve a conta no aplicativo, assinando os eventos de mensagem, status de entrega, mudança de categoria de template e queda de qualidade do número.

São duas coisas diferentes e as duas precisam existir: uma define o destino dos eventos, a outra autoriza a origem. Faltando qualquer uma, não chega nada.

IMPORTANT

Aplicativo em modo de desenvolvimento só recebe webhook de teste. Antes de ligar, o aplicativo precisa estar publicado, como descrito no passo 6 do guia de preparo.

Se a linha listar mais de um aplicativo, ela fica em atenção. A inscrição vale para a conta inteira, então o outro aplicativo recebe os mesmos eventos e pode responder às mensagens deste número por conta própria.

O token de verificação é o mesmo para todo mundo, e isso é de propósito: ele só prova que o endereço é nosso no momento do cadastro. Quem separa uma conta da outra depois disso é a assinatura de cada mensagem, conferida com o App Secret da conexão que a enviou.

Templates

A seção Templates lista o que existe na conta, com categoria, idioma, situação e, para os reprovados, o motivo dado pela Meta. A lista vem da Meta a cada visita.

Um dos templates é marcado como principal, e é ele que os alertas usam. Sem escolha, o envio usa o template padrão da plataforma.

O modelo recomendado tem anexo PDF no cabeçalho e uma linha de texto no corpo com o nome do destinatário, porque é o formato que se sustenta na categoria UTILITY. O botão Criar a partir do modelo monta esse template na conta e o submete para aprovação.

WARNING

A categoria muda o preço. MARKETING custa cerca de três vezes mais que UTILITY, e a Meta reclassifica por conta própria mesmo depois de aprovar. Template com corpo de texto livre ou cabeçalho de imagem quase sempre acaba em MARKETING. A fatura é de quem conectou a conta, então a escolha aparece na tela com o aviso antes de submeter.

Criar template fora do modelo recomendado fica atrás de Modo avançado, com a categoria e o risco de reclassificação escritos na tela.

Situações da conexão

A linha Enviar alertas carrega a situação em que a conexão está.

• Conectada — Enviando.
• Pendente — Credenciais salvas e número ainda não registrado na Cloud API. Falta o PIN, do lado da Meta.
• Precisa reautenticar — O token foi revogado, expirou ou perdeu acesso à conta. Os envios param e voltam para o canal anterior. Acontece quando alguém apaga o System User ou remove a WABA dos ativos dele. Gere um token novo e salve de novo.

Só a situação Conectada envia. Nas outras duas o alerta desce para o próximo dono da lista, em vez de falhar: um Tenant com token revogado volta a sair pelo número do Cliente, e um Cliente sem conexão sai pelo número da plataforma.

Desconectar

Desconectar apaga a conexão e devolve os envios ao dono seguinte. As credenciais são removidas de verdade, não marcadas como excluídas: token revogado não deve continuar hospedado aqui.

Nada muda no ambiente Meta. O número, a conta, os templates e o histórico continuam lá, e reconectar é preencher o formulário de novo. Para cortar o acesso do HorusBI de imediato, apague o System User no Gerenciador de Negócios, o que invalida o token na hora.