Ajuda na conexão Meta

Central de ajuda para seu cliente

Compartilhe a Central de ajuda do WhatsApp Business. Ela é pública, funciona fora desta documentação técnica e reúne orientações sobre conexão, erros, cobrança de mensagens pela Meta e templates. O mesmo acesso fica disponível no rodapé do Connect, junto dos termos e da privacidade.

Atalhos para compartilhar: erros mais comuns da conexão e número não qualificado ou ausente.

Adicione o link ao botão “Preciso de ajuda” no seu próprio sistema. Use apenas a URL pública da central: não inclua a API Key, o token de conexão, os dados pessoais ou os IDs de outro cliente.

Esta página é para a equipe que integra e atende seus clientes. A central explica a jornada ao responsável pelo número, sem expor pacotes ou preços comerciais do Partner.

Identifique a etapa e a evidência

Erros dentro da janela Meta

A janela não abre, não avança ou apresenta erro genérico

Oriente o cliente a permitir pop-ups e os recursos necessários do navegador para os domínios da Meta. Confira se ele entrou com o perfil que tem acesso à empresa e aos ativos pretendidos. Consulte o status oficial da Meta. Uma tentativa em perfil limpo pode ajudar a identificar conflito de sessão; não peça a senha do Facebook nem recomende desativar as proteções da conta.

O código de SMS ou ligação não chega, ou há muitas tentativas

Confira telefone, DDI, controle da linha e recepção de SMS ou chamada. Quando a Meta limitar as tentativas, pare de reenviar e respeite o prazo informado. Não alterne repetidamente os canais nem abra várias sessões. Use somente o código válido mais recente no campo da Meta; ele nunca deve ser enviado ao suporte.

Número já registrado ou vinculado a outra empresa

Identifique primeiro se o objetivo é coexistência com o WhatsApp Business no celular, Cloud API ou migração de outro provedor. Confira a empresa, a WABA e o número corretos. Se o cadastro existente for oferecido, selecione-o. A ausência na lista não comprova vínculo com outro parceiro, e um registro anterior pode estar saudável. Não apague número, WABA, parceria ou conta do aplicativo para “testar”.

Número não aparece ou está “Não qualificado”

Confira o perfil, as permissões, a empresa selecionada e a modalidade oferecida pela integração. No fluxo de coexistência, verifique o WhatsApp Business no celular e sua versão. Leia o detalhe da mensagem; região, vínculo anterior, modalidade e elegibilidade exigem verificações diferentes. Não há prazo universal de “aquecimento” nem quantidade de mensagens que garanta aprovação. Não oriente atividade artificial.

Acesso avançado do aplicativo ou erro de configuração da integração

Se a janela informar que o aplicativo não tem o acesso necessário, preserve a mensagem exata e encaminhe à equipe de integração. O responsável pelo número não precisa criar outro App Meta para corrigir permissões do aplicativo usado pelo Connect. A equipe HookCloud deve conferir a configuração do aplicativo e a tentativa; a equipe do parceiro deve conferir seu próprio fluxo. Não atribua a causa ao celular sem evidência.

Conta restrita, revisão ou limite de criação de empresas

O responsável deve abrir o Business Support Home e o WhatsApp Manager da empresa correta, identificar o ativo e seguir a ação ou revisão que a Meta disponibilizar. Repetir a autorização não remove uma restrição. Não recomende outra conta ou portfólio para contornar limites. Preserve uma operação existente enquanto investiga.

Referência: erros do Embedded Signup da Meta. As mensagens variam por modalidade; compare o texto completo, não apenas palavras isoladas.

Códigos e estados diferentes

Use um código somente quando ele vier na resposta ou na mensagem. A lista abaixo reúne situações diferentes do cadastro e da operação; não significa que todos esses códigos apareçam no pop-up.

Fontes: códigos de erro oficiais da Meta e contrato de conexão e saúde da HookCloud. Os códigos com prefixo meta_ e operation.status pertencem ao contrato da HookCloud.

Retomar sem duplicar a instância

1. Localize a instância já criada pelo instance_id ou instance_key armazenado no seu sistema.
2. Leia get-partner-instance e confira a operação atual, a conexão e as ações permitidas. Se estiver processando, aguarde. Se o resultado estiver incerto, reconcilie antes de repetir.
3. Se o link venceu ou é necessário reiniciar a autorização, use create-connect-session para a mesma instância, com o modo apropriado: connect para conexão ou reconnect para retomar a mesma identidade.
4. Guarde connect_session_id e o prazo exato expires_at da nova sessão. A validade do link não representa validade do número nem cancelamento da assinatura.
5. Abra o connect_url somente para o usuário autorizado. Não publique esse link completo em chamado, log público ou URL da central de ajuda.

O modo replace é reservado à substituição explicitamente autorizada de identidade Meta e tem requisitos próprios. Ele não é um modo de recuperar erro genérico. Não use create-partner-instance ou create-customer-instance para renovar um link.

Confirme o resultado no backend

Voltar ao seu sistema, fechar o pop-up ou concluir a seleção de ativos não comprova que todas as etapas técnicas terminaram. O redirecionamento para adicionar pagamento também não deve ser interpretado como conexão concluída ou cancelamento definitivo.

1. Ao retornar, consulte a instância na Partner API pelo seu backend. Não exponha a Partner API Key no JavaScript do navegador.
2. Leia connection_status, operation.status, connection_health.ready_to_operate, issues[], datas e a indicação de evidência antiga. Vínculo conectado e envio disponível são informações diferentes.
3. Atualize seu cache pelos eventos assinados hookcloud.instance.updated e hookcloud.instance.health_updated. Confira instância, identidade e geração; um evento antigo não pode sobrescrever uma reconexão mais recente.
4. Reconcilie por get-partner-instance quando necessário. Use Webhooks para os contratos completos e Conexão e saúde Meta para interpretar os campos.

Pagamento, mensagens e templates

Encaminhe o responsável pelo número à central de ajuda para entender as cobranças da Meta, os tipos de mensagem e a análise de templates. O pagamento do software contratado com o parceiro é separado do faturamento da conta WhatsApp Business na Meta.

Guias para o responsável pelo número: como a Meta cobra pelas mensagens e templates, análise e entrega.

Uma pendência financeira não é banimento. meta_payment.status=confirmed indica fonte de pagamento identificada para a WABA; no_issue_detected significa que não foi detectada uma pendência na observação, sem confirmar método. unknown pede evidência atual. Não transforme esses estados em “cartão aprovado”, “saldo garantido” ou entrega assegurada.

Templates podem estar em análise, aprovados, reclassificados, pausados ou rejeitados. Aprovação não garante entrega de toda mensagem. Preserve idioma, categoria, motivo e eventos de status. Use as rotas de templates e envio de mensagens com os critérios e consentimentos aplicáveis.

Tarifas, regras de gratuidade, categorias e elegibilidade devem ser conferidas na documentação oficial de preços da Meta. A central mantém o guia para o usuário final sem expor os preços comerciais dos pacotes Partner.

Encaminhamento ao suporte

O usuário final deve procurar primeiro o suporte do sistema que contratou. A equipe do parceiro reúne a evidência e aciona a HookCloud quando o caso envolve o Connect, a integração ou um diagnóstico que depende da plataforma. Questões de políticas, elegibilidade e revisões da Meta seguem os canais que ela disponibilizar; não prometa liberação ou prazo externo.

• Etapa e mensagem completa; código somente se realmente apareceu.
• Data, hora e fuso da tentativa.
• Cliente e instância envolvidos; WABA e phone_number_id quando já disponíveis.
• request_id, operation_id e connect_session_id quando a HookCloud os tiver retornado.
• Objetivo da conexão: manter Business App, Cloud API, reconexão ou migração.
• Captura com dados pessoais desnecessários ocultos.

Na primeira tentativa podem ainda não existir IDs de conexão. Isso não invalida o aviso visto pelo usuário. Não exija um identificador que ainda não foi emitido para iniciar a investigação.

Referências oficiais

• Meta — Embedded Signup: etapas e escopo da autorização.
• Meta — erros do Embedded Signup: mensagens e verificações da jornada.
• Meta — códigos de erro: respostas de registro, conta, pagamento e mensagens.
• Meta — preços do WhatsApp Business Platform: categorias, cobrança e regras vigentes.
• Meta — Business Support Home: avisos e recursos dos ativos autorizados.
• Meta Status: incidentes oficiais.