Conexão, saúde Meta e capacidade

Estados separados

Registro do número ainda não confirmado pela Meta

Concluir o Embedded Signup e manter status=connected confirma o vínculo técnico salvo. Se a observação do número exato trouxer PENDING, PENDING_REGISTRATION ou UNVERIFIED, a disponibilidade de envio ainda não está confirmada. Uma WABA com envio AVAILABLE, um nome aprovado ou um método de pagamento identificado não substituem a confirmação do registro desse número.

Na ausência de bloqueio, limitação ou restrição real com prioridade, o contrato apresenta:

Mostre Confirmação pendente na Meta e preserve o vínculo existente. Este motivo sozinho não gera banimento, desconexão, nova conexão, liberação de vaga nem alteração de cobrança. Evidências de bloqueio, limitação ou restrição reais continuam com prioridade; não recalcule a saúde a partir de um único campo.

A classificação reutiliza a observação já armazenada e não adiciona GETs à Meta ao abrir Portal, Admin, Connect ou consultar a Partner API. Receba hookcloud.instance.health_updated, mantenha seu cache e reconcilie por get-partner-instance ou list-partner-instances. Confira evidence.checked_at, identidade, geração e indicação de evidência antiga. Não repita automaticamente cadastro ou autorização para tentar remover o aviso.

Pagamento e verificação da empresa

A HookCloud consulta a fonte de pagamento da conta WhatsApp separadamente da saúde de mensagens. Um identificador de financiamento retornado para a WABA correta permite mostrar método identificado; o identificador financeiro e os dados do cartão não são expostos. Falha de permissão, campo ausente ou resposta vazia não significam ausência de cartão. A remoção do erro 141006, sozinha, produz no_issue_detected, não confirmed. Uma pendência continua prioritária mesmo se existir uma fonte de pagamento.

A verificação empresarial usa a resposta explícita do portfólio. Se esse acesso estiver indisponível, pode usar a verificação da WABA apenas quando seu proprietário corresponder ao mesmo portfólio. Pagamento cadastrado e nome aprovado não verificam a empresa.

Seu sistema recebe hookcloud.instance.health_updated quando os estados de saúde mudam, incluindo pagamento e empresa. Atualize seu cache com esse evento e reconcilie com get-partner-instance ou list-partner-instances, que leem dados da HookCloud. Não use polling frequente na Graph. Eventos podem atrasar e a Meta pode demorar para propagar alterações; confira as datas e a indicação de evidência antiga.

Ativo com pendência financeira

Quando a única evidência impeditiva é 141006, completa e correspondente à WABA exata, o inventário permanece Ativo. O card informa: “A Meta informou um problema com o meio de pagamento (erro 141006). Confira a forma de pagamento no WhatsApp Manager.”

Isso não confirma envio liberado: messaging_capability.state=blocked e ready_to_operate=false podem continuar. A regra não oculta BAN, violação, restrição independente, resposta truncada ou erros mistos. 131042 não é prova genérica de ausência de cartão nem recebe automaticamente a exceção 141006.

O cartão da assinatura HookCloud na Stripe é separado do pagamento das tarifas Meta. Ausência de permissão ou falha de consulta não deve ser mostrada como “sem cartão”.

Primeira conexão registrada

first_connected_at é um campo somente de leitura: data ISO 8601 em UTC (por exemplo, 2026-10-08T14:30:00.000Z) ou null. Em list-partner-instances, aparece em cada items[]; em get-partner-instance e refresh-partner-instance-meta, na projeção da instância retornada.

A data representa a primeira evidência registrada e ainda disponível de uma conexão técnica confirmada para o mesmo meta_phone_number_id dentro do parceiro. Não afirma a primeira conexão de toda a vida do número. Reconectar o mesmo número, movê-lo para outro cliente ou mesclar clientes dentro do mesmo parceiro preserva o registro. Uma nova identidade de número ou outro parceiro não herda a data anterior.

Quando não há histórico suficiente, mostre “Não informado”. Não substitua null por created_at, data de cadastro do cliente ou connected_at. A primeira conexão registrada não é a última atualização da Meta: para a atualidade de cada diagnóstico, continue lendo suas datas de observação e stale. Uma data de conexão não confirma que o envio está disponível.

{
  "first_connected_at": "2026-10-08T14:30:00.000Z"
}

Sem evidência preservada, o mesmo campo retorna "first_connected_at": null. Seu sistema não deve enviar ou sobrescrever esse valor.

Acesso ao WhatsApp Manager pelo seu sistema

Botão “Abrir WhatsApp Manager” no seu painel

Use get-partner-instance para obter whatsapp_manager_url na raiz da resposta e oferecer o mesmo acesso que existe no Portal HookCloud. Não é necessário criar um endpoint exclusivo, revelar o token Meta ou iniciar outra conexão.

1. No backend do seu sistema, consulte GET ?route=get-partner-instance&instance_id=UUID_DA_INSTANCIA com a autenticação Partner API e o escopo instances.read. Use apenas um identificador por consulta.
2. Verifique se a pessoa autenticada no seu sistema tem acesso àquele cliente e número antes de devolver os dados ao navegador. A Partner API Key permanece no seu backend.
3. Leia whatsapp_manager_url. Ela contém os identificadores Meta disponíveis do portfólio, WABA e/ou número. Use a URL retornada, sem acrescentar tokens ou reconstruí-la a partir do telefone ou BSUID.
4. Se houver uma URL válida, mostre o botão abaixo. Se vier null, ausente ou inválida, mantenha o botão oculto e remova o link anterior. Não abra um endereço de outro cliente como alternativa.

O clique abre uma nova aba na Meta. O usuário precisa entrar com sua própria conta Facebook e ter permissão no portfólio/WABA correspondente; esse link não faz login automático nem concede acesso. Dependendo da sessão, a Meta pode pedir login ou seleção da empresa.

A presença do link não confirma que o número está conectado, saudável ou autorizado para envio. Para esses estados, leia connection_health. A consulta da instância usa dados armazenados na HookCloud; reutilize a URL no seu painel. Não chame refresh-partner-instance-meta nem a Graph API só para renderizar o botão.

<a id="abrir-whatsapp-manager"
   target="_blank"
   rel="noopener noreferrer"
   hidden>
  Abrir WhatsApp Manager
</a>

function atualizarBotaoWhatsAppManager(dadosDaInstancia) {
  const botao = document.getElementById('abrir-whatsapp-manager');
  if (!botao) return;

  // Remova qualquer URL anterior ao trocar de cliente ou instância.
  botao.hidden = true;
  botao.removeAttribute('href');

  const endereco = dadosDaInstancia?.whatsapp_manager_url;
  if (typeof endereco !== 'string' || !endereco.trim()) return;

  try {
    const url = new URL(endereco);
    if (url.origin !== 'https://business.facebook.com') return;
    if (url.username || url.password) return;

    botao.href = url.href;
    botao.hidden = false;
  } catch {
    // URL indisponível ou inválida: mantenha o botão oculto.
  }
}

// Após seu backend devolver os dados autorizados da instância:
// atualizarBotaoWhatsAppManager(dadosDaInstancia);

Inclua o HTML no card do número e execute atualizarBotaoWhatsAppManager(dadosDaInstancia) após carregar a resposta autorizada. O exemplo usa um único botão; em uma lista, use uma referência própria por card, sem repetir o mesmo id. A consulta autenticada acontece no seu backend: nenhum segredo HookCloud ou Meta deve ser colocado neste JavaScript do navegador.

Consultar conexão e saúde do número: autenticação, parâmetros e resposta · API Reference

Leitura, atualização e sistema externo

1. Consulte list-partner-instances com page e page_size, ou get-partner-instance com um identificador exato.
2. Renderize os campos recebidos, incluindo data, unknown e mensagens. A listagem não dispara consulta Graph por número.
3. Use refresh-partner-instance-meta para atualização explícita e limitada. Respeite cooldown e eventuais operações em andamento; não refaça OAuth, registro ou callback como tentativa de diagnóstico.
4. Após atualizar, leia a fotografia novamente. Não converta HTTP 200 em prova de disponibilidade.

O assinante controla seu próprio sistema e código. Não há dependência de Chatwoot. Saúde de Entregas utiliza as evidências que foram reportadas ao Partner; isso não é histórico completo de conversas. Reenvio de mensagem exige operação própria e autorização, não nasce de uma consulta de saúde.

BAN, RED e avisos

BAN/desativação confirmada, restrição, violação, aviso de futura desativação e qualidade RED não são sinônimos. Telefone de teste conectado não libera WABA banida. Exclusão de número e erro de permissão não comprovam restauração; prova posterior deve corresponder à mesma identidade.

A política do Partner usa 20 episódios de BAN ou 5 de RED por cliente em janela móvel de 30 dias. Histórico novo tem cobertura desde sua implantação; não há preenchimento fictício de episódios anteriores. A próxima saída e a liberação estimada dependem do histórico conhecido e de eventual revisão manual. Reconhecer alerta ou ocultar aviso não resolve incidente nem suspende o controle do servidor.

Capacidade e faturas

get-partner-billing-summary mantém os campos antigos e acrescenta capacidade paga no ciclo (paid_capacity_current_period), em uso (used_slots), reservada (reserved_slots), livre (available_slots) e prevista para renovação (renewal_capacity). Não some uma reserva consumida novamente.

Capacidade paga é nula sem prova financeira; trial não é mensalidade paga. paid_period, observed_period, original_contract_started_at, next_billing_at e latest_invoice expõem datas e evidências disponíveis. Dados ausentes continuam nulos. Compra voluntária de pacote é diferente de conexão utilizando vaga já paga.

Cláudia e evidência

Informe um número completo, instance_id ou instance_key: sua-chave na mensagem atual. A assistente consulta somente dados autorizados do parceiro, com paginação limitada e conferência da identidade. Leitura do banco não é nova consulta à Meta. Referência ambígua, cobertura incompleta ou identidade alterada gera pedido de confirmação, sem escolher outro número.

Uma solicitação de atendimento humano interrompe novas respostas da IA e respostas em andamento; a equipe retoma a IA explicitamente. Não há prazo de atendimento ou acompanhamento individual OBA/governo prometido por esse fluxo.

Políticas Meta que exigem confirmação atual

OBA, verificação empresarial e Meta Verified são assuntos distintos. Critérios de governo, migração, limites, preços e avisos de vigência da Meta devem ser conferidos na fonte oficial aplicável. Este documento não incorpora números ou regras temporárias do Flow. A tentativa de revalidar os caminhos de OBA, erros e preços em 28/09/2026 recebeu indisponibilidade HTTP 429; não foi usada para afirmar mudança de política.

OBA · Preços Meta · Erros Meta · Status WhatsApp Business

Estados do card e conclusão da desconexão

panel_category é a categoria de exibição calculada pela HookCloud: active, processing, verification_pending, account_alert, restricted, banned, callback_review, attention ou disconnected. O Portal reúne históricos confirmados em Substituídos, com o subtipo no próprio card; não há abas separadas de Transferidos ou Encerrados. connection_history registra trocas de identidade confirmadas, com status superseded e subtype meta_identity_replacement. Uma reconexão normal pode atualizar os IDs automaticamente quando a nova autorização e a consulta à Meta comprovam o mesmo número, com o vínculo anterior encerrado. Mover uma instância entre clientes, reconectar sem mudança de IDs ou apenas observar um telefone igual não cria histórico de substituição. Não derive banimento de pagamento, RED ou erro técnico. A categoria não altera vagas nem permissões: use allowed_actions e occupies_slot. Após desconexão concluída, status legado permanece canceled, connection_status é inactive e observation_scope é historical. Falha de callback ou de credencial, isoladamente, não é histórico de desconexão.

No Portal, a solicitação mostra andamento imediatamente e um contador de tempo decorrido. O acompanhamento inicial dura até 120 segundos; sem confirmação, o aviso passa a pedir acompanhamento/revisão. A atualização usa o cache da HookCloud, não uma nova leitura Graph. Processamento aparece em azul, pendências em âmbar, BAN e falha de callback em vermelho, ativo em verde e desconectado em cinza. Substituídos permanece azul e reúne os subtipos históricos no próprio card, sem abas extras; categorias mantêm suas cores e símbolos mesmo quando não selecionadas.

Uma desconexão confirmada gera instance.canceled e notificação no sininho para o parceiro responsável, independentemente de a ação vir do painel ou da API. Falha, tempo esgotado e limpeza incerta não geram sucesso. Os dados Meta anteriores continuam no histórico e não representam envio disponível.

Reconexão e atualização automática dos IDs Meta

Use o link normal de conexão da mesma instância. Se a Meta atribuir novos identificadores ao mesmo número, a HookCloud verifica os dados e atualiza o vínculo automaticamente, preservando instance_id e instance_key. O usuário não precisa preencher WABA ou Phone Number ID.

1. Confirme o encerramento do vínculo anterior e gere uma sessão com mode=reconnect.
2. O titular abre o link e autoriza o mesmo número no Embedded Signup.
3. A HookCloud confirma diretamente na Meta o número completo, sua WABA e o portfólio. Cobrança, capacidade, risco, concorrência e isolamento entre clientes continuam sendo verificados.
4. Após a conclusão, consulte get-partner-instance para atualizar os IDs no seu sistema. Se houve mudança, receba instance.identity_replaced.

{
  "route": "create-connect-session",
  "instance_key": "hc_inst_exemplo",
  "mode": "reconnect"
}

Selecionar outro número gera replacement_phone_mismatch: use uma nova instância para outro número. Uma identidade antiga ainda ativa, uma limpeza incerta ou acesso insuficiente à Meta impedem a troca automática. Não altere campos técnicos para contornar essas proteções.

connection_history lista até 50 identidades anteriores, somente leitura, com status=superseded, subtype=meta_identity_replacement, gerações anterior/sucessora, IDs Meta, nome, telefone e datas. reason=automatic_same_phone_identity_replacement indica a atualização automática. O modo avançado legado replace continua aceitando geração e destino exatos, com reason=explicit_meta_identity_replacement; ele não é necessário no fluxo normal.

A identidade anterior aparece em Substituídos, sem ocupar outra vaga ou oferecer botões operacionais. Uma sessão cancelada ou incompleta não cria histórico nem muda o cliente. O evento identifica a geração sucessora; em dúvida, reconcilie pelo GET local em vez de repetir a conexão.

Vínculo removido e acesso não confirmado

Erros Graph 100/33 ou 190, isoladamente, não confirmam parceria removida, BAN, callback desligado ou token global revogado. Não transforme uma falha de acesso em um resultado de sucesso. Dados de pagamento e de empresa continuam separados.

A remoção confirmada produz instance.meta_link_removed, notificação no sininho e estado Desconectado — Vínculo removido na Meta. A autorização local é desabilitada; a vaga daquele vínculo é liberada. remote_cleanup_confirmed=false, remote_callback_status=unavailable e remote_authorization=unknown deixam claro que não houve confirmação de limpeza remota. Isso difere de instance.canceled por desconexão remota concluída.

O webhook usa data.meta_link_state com evidence_source; o GET expõe o resumo meta_link com source. Ambos indicam a geração; descarte efeitos de eventos antigos sobre uma nova conexão e reconcilie em caso de dúvida. Nenhuma dessas consultas locais acrescenta leitura Graph.

Desconexão interrompida e parceria na Meta

Solicite a desconexão na HookCloud e aguarde sua confirmação antes de remover a parceria no portfólio empresarial da Meta (BM). Se a parceria for removida primeiro, o acesso necessário para remover ou conferir o callback pode deixar de funcionar. Erros de permissão, objeto inacessível ou token inválido não comprovam que o número foi removido nem que o callback foi desligado.

Uma tentativa encerrada não deve aparecer como “Desconectando” indefinidamente. A consulta da instância e o histórico distinguem operação em execução, interrompida e com resultado remoto não confirmado. A limpeza de operações vencidas não repete chamadas de remoção à Meta e não libera capacidade por tempo decorrido.

operation.remote_cleanup_confirmed só é verdadeiro quando a remoção do callback e o deregistro do número foram confirmados na operação de desconexão. operation.capacity_retained informa a retenção de capacidade associada à operação; o contador atual do pacote continua sendo a fonte para vagas disponíveis. O término da tentativa, uma assinatura cancelada ou a expiração do prazo não apagam credenciais, não resolvem BAN/RED e não provam uma desconexão remota.

Se houver remoção pendente sem operação atual identificável, o Portal mostra uma pendência de revisão. Não use outro número, outra WABA, uma nova compra ou uma nova autorização apenas para destravar a limpeza antiga. A Cláudia consegue explicar os registros da instância exata e encaminhar a pendência; ela não executa desconexões, revoga tokens nem libera vagas.

Chave automática e nome aprovado pela Meta

Na criação, external_customer_id identifica o cliente do seu sistema. A HookCloud gera uma instance_key imutável. Não envie uma chave personalizada para criar: isso retorna instance_key_server_managed. Uma chave já existente continua aceita como referência de compatibilidade, sem criar outro vínculo. Guarde o UUID e a chave retornados e reutilize a instância para reconectar. Para criar com segurança após timeout, envie Idempotency-Key (8 a 200 caracteres), estável para o número desejado: mesmo parceiro, cliente e chave reaproveitam a mesma instância; outra chave cria outra. A forma alternativa é idempotency_key no body. Sem essa chave, não repita a criação sem reconciliar o resultado.

customer_name e instance_name podem servir de nomes provisórios. Quando o nome de exibição for aprovado, instance_name acompanha o nome verificado da Meta. Tentar substituí-lo por outro nome retorna instance_name_managed_by_meta. Você pode guardar um apelido próprio em seu sistema, separado do nome oficial.

O GET existente traz verified_name, name_status, meta_business_id, meta_business_name, meta_waba_id, meta_waba_name, meta_synced_at e os metadados de sincronização disponíveis. A atualização automática é eventual: a rotina normal trabalha com alvo de 30 minutos mais uma distribuição de 0 a 60 segundos entre instâncias, acrescidos do tempo de cron e fila. Estados pendentes de nome, pagamento ou empresa também seguem essa rotina; não geram consultas permanentes a cada cinco minutos. Eventos administrativos assinados da identidade correspondente podem antecipar uma rodada: há uma janela limitada de três minutos e orçamento de até três tentativas por 30 minutos. Cada evento invalida somente o domínio pertinente; a nova leitura de empresa, pagamento ou perfil respeita um piso de 15 minutos desde a observação anterior. Cache, permissões, orçamento global da Meta e recuo após falhas podem ampliar o prazo. Portal e Admin consultam o cache local enquanto a atualização automática está ativa e a tela disponível; abrir a tela não dispara GETs à Meta. Não há garantia de atualização instantânea nem de que a Meta emita evento para toda alteração de cartão. Use hookcloud.instance.updated e hookcloud.instance.health_updated para atualizar seu cache e o GET para reconciliar.

Limite Meta e username comercial: perfil opcional

meta_profile contém as observações de messaging_limit e username. O objeto aparece na projeção da instância e dentro de connection_health.meta_profile; na listagem, fica em cada item de items[]. Esses dados são informativos e não alteram por si só a saúde, pagamento, capacidade contratada ou a permissão de envio.

O perfil opcional usa cache de até 6 horas, incluindo respostas indisponíveis, vinculado à identidade exata e à geração da conexão. O GET lê esse cache. Um refresh normal da saúde também pode reutilizá-lo; o refreshed_at geral não significa que limite e username foram consultados novamente. Eventos relevantes assinados podem antecipar somente o domínio correspondente, após o piso de 15 minutos e conforme fila, orçamento de leitura e backoff. Quando a observação expira, os valores positivos ficam neutros até nova confirmação.

Mudanças materiais em limite ou username são notificadas em hookcloud.instance.health_updated, dentro de connection_health.meta_profile. Alterar somente o horário da leitura ou stale não gera eventos repetitivos. No estado público de instância, messaging_limit_tier, business_username e business_username_status são aliases de compatibilidade derivados do mesmo objeto. O nome do alias messaging_limit_tier não garante origem legada: leia sempre meta_profile.messaging_limit.scope e source.

O limite não é a franquia financeira de mensagens nem a quantidade de números comprada na HookCloud. TIER_UNLIMITED não elimina limites de requisições, throughput, políticas e elegibilidade da Meta. Não use a faixa para recalcular ready_to_operate.

Referências oficiais: Limites de mensagens da Meta · BSUID e usernames. Contratos e exemplos: evento de saúde.

Limites de BAN e RED por cliente do parceiro

A política da HookCloud avalia separadamente cada cliente/assinante cadastrado sob o parceiro: 20 episódios de banimento ou 5 episódios de RED em uma janela móvel de 30 dias interrompem novas conexões desse cliente. Não é uma soma de todos os clientes do parceiro. Vagas livres no pacote não substituem essa regra. Conexões existentes não são desligadas por esse limite.

Callbacks repetidos e observações repetidas do mesmo episódio não criam novas infrações. Restauração comprovada encerra um episódio, mas não apaga sua ocorrência da janela de 30 dias. Renomear, mesclar, mover ou recadastrar uma identidade/ativo já conhecido não deve zerar seu histórico.

Leia o objeto customer_risk: scope=customer, ban_count_30d, red_count_30d, limits, window_days, block_new_connections, reasons, next_exit_at, next_exit_quantity e next_unlock_at. Datas são uma projeção dos episódios conhecidos; novos eventos podem mudar o resultado. history_complete e history_started_at indicam a cobertura da coleta, sem inventar ocorrências anteriores.

Receba o evento assinado hookcloud.customer.risk_updated, com data.partner_customer_id e data.customer_risk, e mostre a orientação no painel do cliente. Para recuperar uma notificação perdida, releia o cadastro e o diagnóstico da instância na Partner API. O webhook informa; a trava no servidor é a autoridade e não depende de o seu frontend ter recebido o aviso. Pagamento Meta, saúde técnica e capacidade de pacote continuam separados de BAN/RED.

Pagamento Meta e mensagens de serviço desde 1º de outubro de 2026

Segundo a documentação oficial de preços da Meta, consultada em 01/10/2026, cada número comercial tem uma faixa gratuita de 1.000 mensagens de serviço entregues por mês. A partir da 1.001ª entrega de serviço que conta para essa faixa, há cobrança. A franquia é compartilhada entre entregas individuais e de grupo; no grupo, cada destinatário conta como uma entrega. Ela se renova mensalmente e não acumula.

Cadastre uma forma de pagamento válida na conta do WhatsApp Business para evitar interrupção das entregas após consumir a faixa gratuita. A Meta informa que, sem forma de pagamento, as entregas dentro da faixa podem ocorrer e as posteriores deixam de ser entregues. Isso não é um banimento e não comprova que o número esteja bloqueado antes de consumir a faixa. A cobrança da assinatura HookCloud é independente.

Essa faixa não é uma gratuidade geral de todos os tipos de mensagem: templates seguem suas categorias e tarifas. Reações não consomem essa franquia; outras exceções dependem da elegibilidade e das regras atuais da Meta. Não se deduz o consumo da franquia pelo simples número de chamadas POST. Confira a categoria e a precificação do evento de entrega.

Interprete o alerta antes de alterar a saúde

Um alerta descreve algo informado pela Meta em uma data. Ele pode ser uma confirmação, um pedido de atenção ou um impedimento específico. Use o objeto aditivo explanation para apresentar título, resumo, impacto, orientação, assunto, tom, referência e código técnico. O contrato completo e um exemplo estão em Notificações: explicações de alertas Meta.

• Segurança: PIN_RESET_SUCCESS recebe a descrição “Redefinição do PIN concluída”. Confira se a ação foi autorizada; não transforme esse evento em banimento, falha de pagamento ou prova de invasão. A configuração atual do PIN pode ser diferente da registrada no evento.
• Nome, empresa e selo: aprovação do nome, verificação da empresa, análise da conta e selo oficial têm significados diferentes. Recusa do selo não significa banimento. Nome em análise, isoladamente, não prova bloqueio de mensagens.
• Conta: DISABLED_UPDATE depende de ban_info.waba_ban_state. REINSTATE é restabelecimento; SCHEDULE_FOR_DISABLE é aviso futuro; DISABLE informa desativação. Restrições devem indicar as funções afetadas.
• Pagamento: o erro 131042 aponta uma pendência de cobrança com várias causas possíveis; não comprova ausência de cartão. payment_configuration_update trata do gateway da API de Pagamentos Brasil/Índia, não confirma a forma de pagamento das mensagens à Meta.
• Qualidade e templates: qualidade baixa merece acompanhamento, mas não é automaticamente banimento. Recusa ou pausa de template afeta aquele modelo; reclassificação de categoria pode alterar tarifas sem significar rejeição.

explanation.tone orienta a apresentação; não é uma regra de bloqueio. Não derive BAN, RED, capacidade, liberação de envio ou desconexão de textos ou títulos. Preserve severity, status e evidência original; use os estados estruturados de saúde e risco para decisões operacionais. Um evento desconhecido recebe recognized=false e orientação neutra.

As explicações são calculadas localmente, sem GET à Meta por abertura de tela. O usuário final pode consultar o guia de indicadores e alertas. Referências: segurança, API de Pagamentos e códigos de erro.

Ativo com envio limitado pelo nome de exibição

A Meta pode confirmar o número como conectado e, na consulta de saúde, associar um limite de mensagens à aprovação do nome de exibição. Essa observação de capacidade não substitui o estado do nome: os campos podem ser atualizados em momentos diferentes. Quando a evidência atual e completa identifica somente essa condição, o número permanece em Ativos. A capacidade de envio continua limitada; não é apresentada como envio sem limitações.

Exemplo parcial da resposta

{
  "connection_health": {
    "connection_status": "connected",
    "inventory_state": "active",
    "panel_category": "active",
    "state": "limited",
    "messaging_capability": {
      "state": "limited",
      "reason": "display_name_capacity_limit"
    },
    "ready_to_operate": false
  }
}

Essa classificação depende da identidade correta do número, evidência recente e completa, vínculo operacional e ausência de outras pendências com prioridade. Não se aplica automaticamente a todo nome sem aprovação. Registro pendente, BAN, qualidade RED, rejeição do nome, falha de autorização ou callback, pagamento com ação necessária, erros desconhecidos ou dados antigos continuam sendo tratados separadamente. Não derive o motivo pelo nome do card nem por uma mensagem de texto enviada pelo usuário.

Nome informado não é nome aprovado

verified_name é o texto do nome de exibição; sua presença não comprova aprovação. NON_EXISTS, quando retornado em name_status, não deve ser convertido em “em análise” nem em “aprovado”: não há confirmação de aprovação nesse valor. A mensagem de capacidade registra o que a Meta informou na consulta; não use esse texto para sobrescrever um name_status=APPROVED confirmado para o mesmo número. Mantenha os valores técnicos originais e suas datas para diagnóstico.

O nome foi aprovado, mas o limite ainda aparece

Leia aprovação do nome e capacidade de envio separadamente. Se o nome ainda não tem aprovação confirmada na resposta disponível, a explicação é: “Na última consulta, a Meta associou o limite à aprovação do nome”. Se a HookCloud já recebeu name_status=APPROVED para o número e a observação de saúde ainda traz esse limite, a explicação passa a ser: “O nome consta como aprovado; aguardando a Meta atualizar o diagnóstico de capacidade”. Preserve o nome como aprovado, messaging_capability.state=limited e ready_to_operate=false enquanto essa for a evidência de capacidade.

O WhatsApp Manager e as respostas da API podem não refletir uma alteração no mesmo momento. A HookCloud não garante um prazo de propagação da Meta. Compare os IDs do número e da WABA, evidence.checked_at e a indicação stale. Não force APPROVED ou AVAILABLE para fazer os painéis parecerem iguais e não refaça a conexão apenas por essa diferença.

A atualização automática do Portal consulta os dados já armazenados na HookCloud: o intervalo padrão de 8 segundos não é uma consulta à Meta nem um prazo para uma aprovação chegar. Esse intervalo pode aumentar com o volume de instâncias, e a atualização é pausada durante edição ou enquanto a aba está oculta. Eventos Meta válidos e a sincronização controlada em segundo plano alimentam os dados armazenados; ambos continuam sujeitos à disponibilidade e à propagação da informação na origem.

No seu sistema, receba hookcloud.instance.health_updated e reconcilie por get-partner-instance ou list-partner-instances. Não copie o intervalo do Portal para chamadas à Graph nem repita refresh-partner-instance-meta em um temporizador. Se a divergência persistir, forneça ao suporte os identificadores e as datas das observações, sem tokens ou credenciais.

Ligações via SIP são uma capacidade separada

Os códigos 138024 e 138025 tratam, respectivamente, de SIP não habilitado e de servidor SIP não configurado para ligações do WhatsApp Business. Quando identificados nesse contexto, a HookCloud os apresenta como meta_calling_not_configured, com issues[].domain=calling. Eles, isoladamente, não significam bloqueio de mensagens, banimento ou falta de pagamento. Se seu sistema não usa ligações via SIP, não é necessário configurar esse recurso para resolver o envio de mensagens.

Preserve os domínios de cada diagnóstico. Uma limitação real de mensagens continua relevante mesmo se houver também um aviso de ligações. Não ignore outros erros nem transforme todos os avisos de chamadas em liberação de envio.

Use hookcloud.instance.health_updated para atualizar o cache do seu painel e reconcilie pelos dados armazenados em get-partner-instance ou list-partner-instances. O motivo novo não exige consultas repetidas à Graph API. Para o usuário final, compartilhe o guia de conexão ativa com envio limitado.

Referências oficiais: Health Status: envio limitado, Health Status: chamadas SIP e nomes de exibição.

Desconectar da HookCloud sem interromper outros números

Na coexistência, phone_callback_removed_local_access_disabled com escopo hookcloud_integration comprova a rota removida e o acesso local desativado. Exiba Desconectado da HookCloud somente junto a status=canceled, occupies_slot=false, slot_state=released e à mesma geração/operação. Não é necessário usar o celular para encerrar esta integração.

local_authorization=disabled e token_revocation.status=local_disabled não significam revogação global. remote_authorization=preserved_shared informa que a autorização Meta compartilhada foi preservada para manter outros números. unknown não confirma revogação. A parceria comercial pode continuar visível na Meta.

HTTP 202 com disconnect_status=awaiting_user pode ser legado. Com safe_to_recheck=true e recheck_mode=resume_hookcloud_integration, ofereça Retomar desconexão automática pela mesma chamada de desconexão. O campo legado disconnect_in_whatsapp_business_app não exige celular quando as instruções atuais orientam a retomada. Não transforme esse aviso em sucesso.

disconnect_status=confirming mantém a capacidade até a confirmação. O POST pode prosseguir com uma etapa ainda não iniciada, mas não repete escritas de resultado incerto. O GET apenas lê o estado armazenado. Depois de uma remoção assinada, o GET pode não trazer operation; confira meta_link e a geração correspondente.

Autorização e parceria são vínculos diferentes

A prova anterior grant_revoked_readback, com escopo app_authorization, continua válida quando a revogação foi confirmada independentemente. DELETE /me/permissions não é uma remoção por telefone e o suporte a BISU não deve ser presumido. Não revogue uma autorização compartilhada apenas para desligar uma instância. A desativação local não invalida uma cópia de token que já tenha sido entregue a um sistema externo; esse sistema deve cessar seu uso.

A desconexão individual não remove a parceria comercial. O encerramento definitivo do cliente avalia essa relação em uma fase separada, com inventário completo e proteção das conexões e ativos que ainda dependam dela. Não apague a conta WhatsApp nem outras parcerias.

Orientação para o titular · Offboarding Meta · Autorizações de integração empresarial