WhatsApp

O SteerCrew conecta um número oficial do WhatsApp Business por empresa, organiza conversas e pode iniciar automações. A configuração preferencial é o Embedded Signup da Meta; o formulário manual existe para implantação assistida.

Nunca publique access token, app secret ou verify token nesta wiki, em chamados ou capturas de tela. Use os campos protegidos do sistema e placeholders em exemplos.

O que você precisa

• Uma conta Meta com acesso ao Business Portfolio que será usado.
• Um app Meta configurado para WhatsApp e com Embedded Signup habilitado.
• Uma WhatsApp Business Account e um número elegível para conexão.
• Domínio público com HTTPS para OAuth e webhook.
• Variáveis globais da Meta configuradas no ambiente; veja Configuração de ambiente.
• Usuário administrador do SteerCrew para conectar ou trocar a conta.

URLs que devem ser públicas

Substitua https://app.exemplo.com pelo domínio real do ambiente:

OAuth redirect:        https://app.exemplo.com/meta/whatsapp/oauth-callback
Webhook WhatsApp:      https://app.exemplo.com/webhooks/whatsapp
Deauthorize callback:  https://app.exemplo.com/meta/deauthorize
Data deletion:         https://app.exemplo.com/meta/data-deletion

Cadastre as URLs exatamente, incluindo HTTPS e caminho. O webhook global identifica a empresa pelo phone_number_id; não crie um app Meta por cliente sem uma necessidade operacional específica.

Configurar o app Meta

1. No painel do app Meta, habilite o produto WhatsApp e o fluxo de Embedded Signup.
2. Cadastre o redirect OAuth mostrado acima.
3. Cadastre o callback do webhook e use o mesmo verify token configurado no ambiente.
4. Assine os eventos de mensagens necessários para a conta WhatsApp Business.
5. Cadastre deauthorize e data deletion callbacks.
6. Confirme que o app está no modo adequado para as contas que serão conectadas.

O verify token prova a configuração inicial do webhook. Nas entregas posteriores, o sistema valida X-Hub-Signature-256 com o app secret global. Em produção, um app secret ausente faz o webhook recusar a requisição.

Conectar pelo Embedded Signup

1. No SteerCrew, acesse Config. WhatsApp.
2. Confirme que a tela indica o Embedded Signup como configurado.
3. Clique em Conectar WhatsApp.
4. Entre na Meta e selecione ou crie a conta empresarial, a WABA e o número.
5. Autorize e conclua o fluxo.
6. Volte ao SteerCrew e clique em Verificar conexão.

O sistema troca o código OAuth, tenta estender o token, resolve WABA e número e ativa a conta encontrada. Ao ativar uma conta, as outras contas WhatsApp da mesma empresa são desativadas.

Validação esperada:

• status Conectado;
• número exibido correto;
• Phone number ID e Business Account ID preenchidos;
• verificação retorna o mesmo número da Meta;
• webhook de teste recebe HTTP 200.

Configuração manual

Use somente quando o onboarding assistido exigir:

1. Abra Config. WhatsApp e o formulário manual.
2. Informe número exibido, Phone number ID e, se disponível, Business Account ID.
3. Cole o access token no campo protegido.
4. Informe o verify token usado para aquela URL de webhook.
5. Informe o app secret se usar o webhook específico da conta.
6. Marque a conta como ativa e salve.
7. Execute Verificar conexão.

Atualizar uma conta sem preencher um novo access token preserva o token atual. Desconectar apenas torna a conta inativa; não revoga permissões no painel Meta. Faça a revogação na Meta quando o acesso não deve mais existir.

Receber mensagens

Quando chega uma entrega válida:

1. O webhook confere assinatura e Phone number ID.
2. O sistema ignora contas desconhecidas ou inativas.
3. Cada mensagem é deduplicada pelo ID do provedor.
4. O telefone é normalizado e usado para localizar cliente e projeto.
5. A mensagem entra na conversa correspondente.
6. O evento whatsapp.message.received é emitido uma única vez.
7. Flows publicados e ativos podem tratar o evento.

Textos, imagens, áudios, vídeos, documentos, localização, contatos, reações, botões e interações aparecem com uma representação legível. A mídia é buscada por rota autenticada; não exponha URLs internas de mídia.

Operar a caixa de entrada

Em WhatsApp:

• Minhas conversas mostra o que está atribuído ao usuário.
• Não atribuídas mostra conversas disponíveis para a equipe.
• Assumir atribui a conversa ao próprio usuário.
• Usuários com supervisão podem atribuir a outro atendente ou encaminhar a uma equipe de escritório.
• Cliente e projeto podem ser corrigidos no contexto da conversa.
• Mensagens manuais têm até 4.096 caracteres.
• O histórico de atividade registra mudanças de atendimento, equipe, contexto e automação.

Ao assumir ou atribuir uma conversa, a automação não deve responder em paralelo. O sistema só considera uma conversa automatizável quando ela não tem atendente e não está bloqueada.

Equipes, supervisão e bloqueio

Somente equipes do tipo Escritório participam do roteamento de atendimento. Use Supervisão para filtrar conversas atribuídas, não atribuídas ou bloqueadas, além de equipe, atendente e busca.

Há duas formas de interromper automações:

• atribuir a conversa a uma pessoa;
• usar Bloquear automação, manualmente ou pelo node de flow correspondente.

Depois do atendimento humano, remova a atribuição conforme o processo da equipe e use Desbloquear automação somente quando for seguro retomar respostas automáticas.

Usar WhatsApp em flows

Use o trigger de evento whatsapp.message.received. Os caminhos mais usados são:

payload.body
payload.from_number
payload.provider_message_id
whatsapp_message.body
whatsapp_conversation.id
customer.name
customer.phone
project.name

Um fluxo típico é:

Mensagem recebida → validar dados → decidir assunto → encaminhar equipe → bloquear automação

O node Enviar WhatsApp pode aguardar resposta. Nesse caso, a execução fica em espera e retoma com a próxima mensagem correlacionada. No modo de teste, envio, conversa e resposta são simulados.

Diagnóstico

Sintoma	Verificações
Embedded Signup indisponível	App ID, Config ID e redirect URI do ambiente; domínio permitido na Meta.
Conexão conclui, mas a verificação falha	Token vigente, Phone number ID, acesso do usuário Meta e permissão sobre a WABA.
Verificação do webhook retorna 403	Modo subscribe, verify token do ambiente e URL exata.
Entrega de mensagem retorna 403	Assinatura X-Hub-Signature-256 e app secret do ambiente.
Webhook responde 200, mas não cria mensagem	Phone number ID ativo no SteerCrew e presença de messages no payload. Eventos apenas de status não criam mensagem.
Mensagem não encontra cliente	Telefone do cadastro e número recebido após normalização.
Mensagem não dispara flow	Flow publicado/ativo, evento correto e conversa sem atendente nem bloqueio de automação.
Envio fica em fila	Worker ativo, conta conectada e logs da mensagem.
Meta recusa o envio	Token expirado/revogado, número, janela/template aplicável e detalhes retornados pelo provedor.

Administradores podem abrir Logs do WhatsApp para correlacionar mensagem, status e retorno técnico. Consulte os logs sem copiar tokens ou payloads pessoais para canais públicos. Para outras verificações, use Diagnóstico.

Checklist de aceite

• [ ] URLs públicas cadastradas com HTTPS.
• [ ] Webhook verificado pela Meta.
• [ ] Conta conectada e verificada no SteerCrew.
• [ ] Mensagem real recebida e vinculada à conversa.
• [ ] Mensagem de resposta enviada por um atendente.
• [ ] Equipe de escritório e permissões de supervisão validadas.
• [ ] Flow de teste disparado sem resposta duplicada.
• [ ] Processo de bloqueio, desbloqueio e expiração de token registrado pela equipe.

Veja também Credenciais, webhooks e integrações e Automações e flows.