WhatsApp Oficial

O WhatsApp Oficial conecta uma conta WhatsApp Business ao SquadOS pela Cloud API da Meta. Cada número conectado vira uma caixa de entrada, que pode encaminhar novas conversas para um agente de IA ativo ou para o atendimento humano.

Este canal é diferente de WhatsApp, Z-API, UAZAPI e Evolution: somente o WhatsApp Oficial usa a janela de atendimento e os modelos aprovados da Meta.

Antes de conectar

Tenha em mãos:

• uma conta Meta com acesso ao portfólio empresarial correto;
• uma WhatsApp Business Account (WABA), criada antes ou durante o cadastro da Meta;
• um número de telefone disponível nessa WABA;
• autorização para conceder as permissões solicitadas no popup;
• o PIN atual de seis dígitos, se o número usa verificação em duas etapas.

O próprio produto orienta que o número não esteja ativo em outro aplicativo WhatsApp Business. Migração, liberação do número, aprovação do nome e requisitos da conta são controlados pela Meta; siga as instruções exibidas no WhatsApp Manager em vez de excluir uma conta ou alterar segurança por tentativa.

Conectar a caixa

1. Abra Caixas de entrada e selecione Conectar caixa de entrada.

2. No grupo WhatsApp, escolha WhatsApp Oficial. Confirme a descrição API oficial da Meta, com número verificado e selecione Conectar com WhatsApp.

3. No popup da Meta, entre na conta correta e conclua todo o Embedded Signup. Escolha ou crie a WABA e selecione o número que será conectado. Se a conta tiver várias WABAs, selecionar o número explicitamente permite ao SquadOS identificar a conta correspondente.

4. Volte ao SquadOS e mantenha a aba aberta enquanto aparece Conectando com a Meta. Isso pode levar até 30 segundos. A caixa só é criada depois que o fluxo devolve dados suficientes e o setup consegue persistir a conexão.

5. Se aparecer Verificação em duas etapas detectada, conclua a seção Verificação em duas etapas antes de avançar. Quando o cartão mostrar Conectado, selecione Continuar.

6. Em Quem atende esta caixa?, escolha Atendimento humano ou um agente de IA ativo. Revise o Nome da caixa e selecione Concluir.

Cuidado

Não trate o estado Conectado como teste de ponta a ponta. Envie uma mensagem de outro número e confirme que a conversa aparece em Conversas e que o destino escolhido consegue responder.

Verificação em duas etapas (2FA)

O estado Verificação do número pendente significa que o Embedded Signup terminou, mas o registro do número ainda não foi ativado. O diálogo aceita exatamente seis dígitos.

• Se você conhece o PIN, preencha PIN de verificação em duas etapas e selecione Registrar com este PIN.
• Se esqueceu, use Redefinir PIN no WhatsApp Manager, siga o procedimento atual da Meta e volte para informar o novo PIN.
• Ou desabilite a 2FA (último recurso) expõe Abrir WhatsApp Manager. Só depois de concluir essa mudança na Meta use Já desabilitei, tentar.
• Se o processo ainda estiver pendente, use Finalizar registro no cartão da conexão.

Um PIN incorreto mantém o registro pendente. Muitas tentativas podem produzir Muitas tentativas incorretas; nesse caso, aguarde o período indicado pela interface ou redefina o PIN na Meta. Não crie outra caixa para contornar esse estado.

O que entra pelo canal

O adaptador atual recebe:

• texto;
• imagem, inclusive legenda;
• áudio;
• documento, inclusive legenda;
• localização, convertida em uma descrição textual para o agente.

Imagem, áudio e documento só chegam ao modelo conforme a configuração de anexos do agente. Tipos que o adaptador não reconhece não são interpretados como mídia útil. Para validar um formato, envie uma amostra real e confira a mensagem persistida em Conversas.

Uma caixa com Atendimento humano cria a conversa sem chamar um agente. Uma caixa destinada a agente depende de esse agente continuar ativo; escolha um agente ativo mesmo que o seletor também mostre outros registros.

Responder e a janela de 24 horas

A janela é contada a partir da última mensagem enviada pelo cliente:

• dentro de 24 horas, agente e operador podem responder com texto livre;
• fora da janela, o compositor bloqueia texto livre e mostra Enviar modelo;
• depois de enviar o modelo, o cliente ainda precisa responder para reabrir a janela de texto livre;
• a regra não se aplica às integrações de WhatsApp por QR Code ou por provedor BYO.

Em Automações, a ação Enviar mensagem também precisa de um modelo aprovado em Fora da janela de 24h. Sem esse fallback, a tentativa vencida é pulada como meta_window_closed. Veja Ações de Automações.

Criar, sincronizar e enviar modelos

Abra Configurações → Modelos do WhatsApp (/settings/whatsapp-templates) para administrar modelos de todas as caixas do WhatsApp Oficial. O menu Ações de uma caixa também oferece Modelos de mensagem.

1. Selecione Novo modelo e, quando houver mais de uma caixa oficial, escolha a caixa proprietária.
2. Preencha nome, idioma, tipo e mensagem. Use {{v1}}, {{v2}} e assim por diante nos trechos variáveis e informe um exemplo para cada um.
3. Selecione Enviar para aprovação. O modelo pode aparecer como Em análise, Aprovado, Recusado ou Indisponível.
4. Use Atualizar para sincronizar o catálogo. Somente modelos Aprovados aparecem no diálogo Enviar modelo.
5. Ao enviar, escolha o modelo, preencha todos os valores variáveis, revise Como a mensagem vai chegar e selecione Enviar modelo.

O catálogo do SquadOS reflete o estado informado pelo WhatsApp. Se não houver modelo aprovado, o diálogo oferece Gerenciar modelos; criar o modelo não libera o envio antes da aprovação.

Estado e detalhes da conexão

No cartão conectado, abra as informações para consultar os dados retornados pela Meta: Nome verificado, Número, Status do número, Qualidade, Limite de mensagens, Modo, Conta oficial, Conta WABA, Verificação do negócio e Webhook URL. Gerenciar no Meta Business Suite abre o ambiente da Meta.

Esses dados são carregados sob demanda e podem ficar em cache por alguns minutos. Use-os para diagnóstico, mas confirme o recebimento e o envio com uma conversa real.

Reconectar, desconectar ou excluir

• Reconectar aparece na linha da caixa apenas quando ela está inativa por uma causa recuperável, como autorização expirada ou registro pendente. Abra essa ação e conclua novamente o fluxo da Meta.
• Desconectar fica no cartão de configuração do canal conectado. A desconexão voluntária remove a caixa da lista; conversas existentes permanecem no histórico, mas não podem mais responder por essa conexão.
• Excluir caixa também remove a credencial. Não use exclusão como tentativa de corrigir 2FA ou aprovação da Meta.

Cuidado

Se a mesma WABA possui mais de um número conectado ao SquadOS, não desconecte um deles sem validar os demais depois. A implementação atual remove a assinatura de webhook no nível da WABA inteira antes de remover a caixa.

Solução de problemas

Mensagem	O que verificar
Não foi possível carregar o SDK da Meta	Recarregue a página e confirme que o navegador não bloqueou os scripts ou o popup da Meta.
Conexão cancelada	Reabra Conectar com WhatsApp e conclua o popup; fechar ou cancelar não finaliza a autorização.
Nenhuma conta WhatsApp Business encontrada	Conclua todas as telas do Embedded Signup e confirme que existe uma WABA acessível.
Mais de uma conta WhatsApp Business encontrada	Repita o fluxo e selecione um número específico para identificar a WABA correta.
Código de autorização expirado ou já utilizado	Inicie uma nova conexão para gerar outro código e conclua sem reutilizar a tentativa anterior.
Nenhum número de telefone na conta	Adicione ou selecione um número no WhatsApp Manager e repita o cadastro.
Falha ao ativar webhook no Meta	Confirme acesso e permissões sobre a WABA. Depois de repetir, valide uma mensagem real.
Falha ao registrar número de telefone	Confirme no WhatsApp Manager o estado do número e se há outro aplicativo WhatsApp Business ativo. Use o fluxo de 2FA se ele aparecer.
Número conectado com restrições	Consulte Verificação do negócio, Modo, Qualidade e Limite de mensagens; conclua na Meta os requisitos indicados para a conta.
Não foi possível obter informações da Meta	A autorização pode ter expirado. Feche e reabra as informações; se a caixa ficar inativa e oferecer Reconectar, reautorize.
O modelo não aparece	Confirme que pertence à caixa/WABA correta, sincronize com Atualizar e verifique se está Aprovado.
O envio não chegou	Confira a faixa de erro na mensagem ou o aviso A mensagem foi salva, mas o WhatsApp não conseguiu entregá-la; conectado e persistido não significam entregue pela Meta.