WhatsApp Oficial (Cloud API)

O WhatsApp Oficial usa a Cloud API da Meta para enviar e receber mensagens. É o modo recomendado para produção: estável, com SLA oficial, limites claros e sem o risco de desconexão que pode ocorrer com soluções via QR Code.

Requisitos

Antes de conectar, você precisa ter:

1. Conta no Meta Business Manager — acesse business.facebook.com. É gratuito.
2. Uma conta WhatsApp Business (WABA) criada e associada ao seu Business Manager. Se ainda não tem, crie uma dentro do fluxo de cadastro ou antecipadamente no Business Manager.
3. Um número de telefone dedicado ao WhatsApp Business — veja a seção Número de telefone para como adicionar.
4. O número não pode estar ativo no aplicativo WhatsApp pessoal ou WhatsApp Business App. Um número só pode ser usado em um lugar por vez.

Cuidado

Se a sua conta Meta tem mais de uma WhatsApp Business Account (WABA), você precisa selecionar um número de telefone específico durante o popup de cadastro — caso contrário o SquadOS não consegue identificar qual conta usar e retorna o erro “Mais de uma conta WhatsApp Business encontrada”. Se isso acontecer, refaça a conexão selecionando o número explicitamente no popup. Contas WABA duplicadas no Meta Business Manager são a causa mais comum — remova as que não usa.

Dica

A verificação do negócio no Meta Business Manager é opcional para conectar, mas necessária para remover limites de envio e sair do modo sandbox em produção.

Como conectar

1. Abra Agentes → [seu agente] → Gatilhos.

2. Na seção Meta, localize o card WhatsApp Oficial (com o badge API Meta) e clique em Conectar.

3. Um popup da Meta se abre — complete todas as etapas do fluxo Embedded Signup:

   • Faça login com sua conta do Facebook Business.
   • Selecione (ou crie) a WABA.
   • Selecione o número de telefone que vai usar.
   • Confirme as permissões solicitadas até o botão final aparecer.

   Cuidado

   Não feche o popup antes de terminar. Completar metade das etapas não devolve um código de autorização válido e resulta no erro “Nenhuma conta WhatsApp Business encontrada”. Isso também ocorre se você reconectar uma WABA que já havia usado antes e não concluir todas as etapas do popup.

4. Após fechar o popup, aguarde até 30 segundos enquanto o SquadOS registra o número na Cloud API. Mantenha a aba aberta.

5. Quando concluído, o card exibe Conectado e o agente começa a receber mensagens.

Número de telefone

Se sua WABA ainda não tem um número configurado, você verá o erro “Nenhum número de telefone na conta” ao tentar conectar.

Para adicionar um número:

1. Acesse o WhatsApp Manager e selecione sua conta WABA.
2. Clique em Adicionar número de telefone.
3. Insira o número, escolha como receber o código de verificação (SMS ou ligação) e confirme.
4. Aguarde a aprovação do nome de exibição pela Meta — pode levar algumas horas.
5. Com o número ativo, volte ao SquadOS e clique em Conectar novamente.

Nota

O número de telefone não pode estar em uso no aplicativo WhatsApp (pessoal ou Business App) ao mesmo tempo que na Cloud API. Se estiver, será necessário migrar ou usar outro número.

Registro

O registro é a etapa final em que o SquadOS ativa o número na Cloud API. Dois problemas comuns nessa etapa:

Número já em uso em outro app

Erro: “Falha ao registrar número de telefone”

O número ainda está ativo no WhatsApp pessoal ou no WhatsApp Business App. Para resolver:

1. No celular onde o número está ativo, abra o WhatsApp e vá em Configurações → Conta → Excluir minha conta — isso libera o número para uso via Cloud API.
2. Alternativamente, use outro número que não esteja em uso em nenhum app.
3. Depois de liberar, volte ao SquadOS e tente conectar novamente.

Verificação em duas etapas ativa

Se o número tem um PIN de verificação em duas etapas configurado, o SquadOS abre automaticamente um diálogo para você informar o PIN. Veja a seção Verificação em duas etapas (2FA) abaixo.

Verificação em duas etapas (2FA)

Se o número que você está conectando já tem verificação em duas etapas ativada — o PIN de 6 dígitos que você configurou no WhatsApp — o SquadOS não consegue finalizar o registro automaticamente e abre um diálogo pedindo o que fazer.

Por que isso acontece: ao migrar o número para a Cloud API, a Meta exige o PIN atual como prova de titularidade. Sem ele, o registro falha com o erro (#133005) Two step verification PIN Mismatch.

Você tem três caminhos, do mais rápido para o último recurso:

1. Informar o PIN atual (mais rápido)

Se você lembra do PIN de 6 dígitos, digite no campo do diálogo e clique em Registrar com este PIN. O SquadOS usa esse PIN para finalizar o registro. Nenhum outro passo necessário.

2. Redefinir o PIN no WhatsApp Manager (recomendado se esqueceu)

Se não lembra do PIN, redefina no WhatsApp Manager:

1. Acesse o Manager e selecione seu número.
2. Vá na aba Confirmação em duas etapas.
3. Clique em Inserir novo PIN e defina um código de 6 dígitos.
4. Volte ao SquadOS e digite o novo PIN no diálogo.

Esse caminho não exige confirmação por e-mail e não desativa nenhuma camada de segurança do seu número. É a forma oficial recomendada pela Meta quando você perde o PIN.

3. Desabilitar a verificação em duas etapas (último recurso)

Só use se os caminhos acima não forem possíveis. No mesmo WhatsApp Manager, em Confirmação em duas etapas, clique em Desativar a confirmação em duas etapas.

• A Meta envia um e-mail de confirmação para o endereço associado ao portfólio de negócio.
• Você precisa clicar no link do e-mail para concluir a desativação.
• Depois disso, volte ao SquadOS e clique em Já desabilitei, tentar no diálogo.

Após o número estar conectado no SquadOS, você pode reativar a 2FA novamente no WhatsApp Manager.

Solução de problemas

Erro exibido	Causa provável	O que fazer
Nenhuma conta WhatsApp Business encontrada	O popup Meta foi fechado antes de concluir todas as etapas, ou você não tem uma WABA; também ocorre ao reconectar uma WABA já usada sem concluir o fluxo novamente	Clique em Conectar novamente e complete todas as etapas do popup. Se não tem WABA, crie uma no Business Manager primeiro
Mais de uma conta WhatsApp Business encontrada	Sua conta Meta tem múltiplas WABAs e o SquadOS não consegue identificar qual usar	Refaça a conexão e, no popup da Meta, selecione um número de telefone específico. Para evitar recorrências, remova WABAs duplicadas no Meta Business Manager
Código de autorização expirado	O código Meta expira em poucos minutos	Clique em Conectar novamente e conclua o fluxo sem demora
Código de autorização já utilizado	Uma tentativa anterior já consumiu o código	Clique em Conectar para gerar um novo código
Falha ao autenticar com o Meta	Erro genérico de autenticação com a Meta	Tente novamente. Se persistir, entre em contato com o suporte
Nenhum número de telefone na conta	Sua WABA não tem números configurados	Adicione um número no WhatsApp Manager e tente novamente — veja Número de telefone
Falha ao ativar webhook no Meta	Permissões insuficientes na WABA	Verifique se sua conta tem as permissões necessárias no Business Manager. Se o problema persistir, entre em contato com o suporte
Falha ao registrar número de telefone	O número está ativo em outro app WhatsApp	Desative o WhatsApp no celular que usa esse número e tente novamente — veja Registro
Número conectado com restrições	WABA ainda não foi verificada pela Meta	O número funciona mas pode ter limites. Conclua a verificação do negócio no Business Manager