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;
para a Coexistência, o número ativo no app WhatsApp Business do celular, na versão mais recente.

No modo Somente API oficial, o número não pode estar no app WhatsApp Business. Para continuar usando o app no celular, conecte pela Coexistência. 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

Abra Caixas de entrada e selecione Conectar caixa de entrada.
No grupo WhatsApp, escolha WhatsApp Oficial.
Escolha o modo de conexão e selecione Conectar com WhatsApp:
- Coexistência: continue usando o app WhatsApp Business no celular e atenda pelo SquadOS no mesmo número;
- Somente API oficial: atenda só pelo SquadOS, com um número que não está no app WhatsApp Business.
No popup da Meta, entre na conta correta e conclua todo o Embedded Signup.
- Na Coexistência, escolha conectar a conta existente do app WhatsApp Business, informe o número e siga as instruções que aparecem no celular, inclusive a de compartilhar o histórico de conversas.
- No Somente API oficial, 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.
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.
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.
Em Quem atende esta caixa?, escolha Atendimento humano ou um agente de IA ativo. Revise o Nome da caixa e selecione Concluir.

Se a conexão não terminar, o aviso mostra o motivo e o botão Ver documentação abre a seção correspondente de Erros de conexão do WhatsApp Oficial.

Coexistência

Na Coexistência, o mesmo número atende pelo app WhatsApp Business do celular e pelo SquadOS ao mesmo tempo. O número continua registrado no app, então a conexão não pede PIN nem registro do número.

Contatos e histórico

Logo depois da conexão, o SquadOS pede à Meta os contatos e o histórico de conversas do app. O cartão da conexão mostra o andamento:

Contatos aplicados indica quantos contatos do app foram ligados aos contatos do SquadOS. A sincronização continua depois da importação inicial.
O histórico aparece como Importando histórico, Histórico importado, Histórico não compartilhado, quando o compartilhamento foi recusado no celular, ou Não foi possível importar o histórico.

As conversas importadas entram em Conversas como encerradas e com o Agente IA desligado. Mídias com mais de 14 dias aparecem como Mídia do histórico indisponível ou expirada.

Respostas pelo celular

As mensagens enviadas pelo app do celular aparecem na conversa do SquadOS. Quando alguém responde pelo celular numa conversa atendida por agente, o Agente IA é pausado naquela conversa, como na intervenção humana.

Limites da Coexistência

Conversas em grupo não aparecem no SquadOS.
O app WhatsApp Business precisa ser aberto no celular pelo menos uma vez a cada 14 dias.
As mensagens enviadas pelo SquadOS são cobradas pela Meta conforme as regras da API oficial. As enviadas pelo app continuam gratuitas.
A janela de 24 horas do SquadOS só conta mensagens do cliente recebidas depois da conexão. O histórico importado não reabre a janela.

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.

A tela aparece para quem configura caixas de entrada e para quem atende conversas. Quem atende pode criar, atualizar e excluir modelos mesmo sem acesso às caixas de entrada.

Selecione Novo modelo e, quando houver mais de uma caixa oficial, escolha a caixa proprietária.
Preencha nome, idioma, tipo e mensagem. Use {{v1}}, {{v2}} e assim por diante nos trechos variáveis e informe um exemplo para cada um.
Selecione Enviar para aprovação. O modelo pode aparecer como Em análise, Aprovado, Recusado ou Indisponível.
Use Atualizar para sincronizar o catálogo. Somente modelos Aprovados aparecem no diálogo Enviar modelo.
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.

Solução de problemas

Cada aviso de erro da conexão tem sua seção em Erros de conexão do WhatsApp Oficial. A tabela abaixo cobre os demais avisos do canal.

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.
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.