SW Shopware 6 Shopware Intermédio

WhatsApp Commerce Suite Shopware: guia de instalação e configuração

Instalar a extensão, ligar a Meta Cloud API, configurar o webhook, os templates HSM e os 4 módulos no Shopware 6.5, 6.6 e 6.7.

Atualizado Versão do módulo 1.0.0

Pré-requisitos

  • Shopware 6.5, 6.6 ou 6.7 (base de código única), PHP 8.1 no mínimo
  • Uma conta WhatsApp Business com um número verificado no Meta Business Suite
  • Uma app Meta do tipo Business com o produto WhatsApp ativado
  • O worker da fila de mensagens e o runner de tarefas agendadas do Shopware ativos (messenger:consume e scheduled-task:run)

Instalação

  1. Copie a pasta DfWhatsAppCommerce para custom/plugins/ (ou carregue o zip em Extensões → As minhas extensões).
  2. Instale e ative: 
    bin/console plugin:refresh
bin/console plugin:install --activate DfWhatsAppCommerce
bin/console cache:clear
  3. Compile a administração e o storefront: 
    bin/build-administration.sh
bin/build-storefront.sh
A instalação cria 5 tabelas dedicadas com o prefixo df_wac_ e 2 tarefas agendadas (recuperação de carrinho a cada 15 min, lote de catálogo de hora a hora). Tudo é eliminado corretamente na desinstalação, exceto se marcar «conservar os dados».

Configuração da Meta Cloud API

1. Obter as credenciais

Em developers.facebook.com, crie uma app Business e acrescente o produto WhatsApp. Obtenha: o token permanente (utilizador de sistema com as permissões whatsapp_business_messaging e catalog_management), o Phone number ID, o WABA ID e o App secret (Definições da app → Geral).

No Meta Commerce Manager, crie um catálogo e ligue-o à sua conta WhatsApp Business. Anote o ID do catálogo.

3. Configurar o webhook

Na app Meta → WhatsApp → Configuração:

  • URL de callback: https://asualoja.tld/df-wac/webhook
  • Token de verificação: o valor que introduz na configuração da extensão (campo «Webhook verify token»)
  • Subscreva o campo messages
Preencha o App secret na configuração da extensão: sem ele, a assinatura X-Hub-Signature-256 dos webhooks não é validada.

4. Introduzir a configuração no Shopware

Definições → Sistema → Extensões → DataFirefly WhatsApp Commerce Suite. Preencha o cartão «API Meta Cloud» e teste a partir do painel (Marketing → WhatsApp Commerce): botão Testar a ligação à API e envio de uma mensagem de teste.

Os 4 módulos

Catálogo Meta

Três modos: tempo real (a cada gravação de produto), lote de hora a hora, ou manual. As variantes são enviadas individualmente com o retailer_id sw_{número de artigo}. Exclua categorias se for necessário. A ressincronização completa (lotes de 100) lança-se a partir do painel.

Encomenda conversacional

Máquina de estados de 6 níveis. Palavras-chave reconhecidas (FR/EN/DE): menu, panier, payer, humain, reset, aide. O idioma do cliente é detetado automaticamente. A transferência para um humano envia um email ao endereço configurado com a ligação para a conversa.

Recuperação de carrinho abandonado

3 mensagens configuráveis (60 min, 24 h, 72 h por predefinição) enviadas pela tarefa agendada a cada 15 minutos, aos clientes cujo telefone de facturação é conhecido. O código promocional introduzido na configuração é anexado à 3.ª mensagem e aplicado automaticamente ao carrinho restaurado.

Torne o campo de telefone obrigatório em Definições → Loja → Início de sessão / registo para maximizar a cobertura das mensagens de recuperação.

Ligação de pagamento assinada e notificações

As ligações de checkout e de recuperação de carrinho são assinadas com HMAC SHA-256 e têm expiração configurável (72 h por predefinição). Notificações automáticas: confirmação de encomenda, expedição (com n.º de seguimento), falha de pagamento.

Templates HSM a criar no Meta Business Suite

Template Variáveis do corpo Botão
Mensagem 1 e 2 {{1}} nome do cliente, {{2}} total do carrinho URL dinâmico (sufixo = token)
Mensagem 3 {{1}} nome, {{2}} total, {{3}} código promocional URL dinâmico (sufixo = token)
Confirmação {{1}} nome, {{2}} n.º de encomenda, {{3}} total —
Expedição {{1}} nome, {{2}} n.º de encomenda, {{3}} n.º de seguimento CTA de seguimento (opcional)
Falha de pagamento {{1}} nome, {{2}} n.º de encomenda CTA de nova tentativa (opcional)

Para as mensagens de recuperação, o botão de URL do template tem de ter como base https://asualoja.tld/df-wac/cart/restore?token= com o sufixo dinâmico {{1}}. Introduza os nomes dos templates aprovados na configuração da extensão.

Administração

Marketing → WhatsApp Commerce: painel de KPI (conversas, não lidas, carrinhos, taxa de recuperação, erros), página Conversas (fio ao estilo do WhatsApp Web, resposta direta), Carrinhos abandonados, Catálogo (registo de sincronização) e Registos (filtros por nível e canal).

Regra da Meta: as respostas livres a partir da administração só são entregues nas 24 h seguintes à última mensagem do cliente. Depois disso, use um template HSM.

Resolução de problemas

  • Não aparece nada no frontend: verifique que o «Número WhatsApp público» está preenchido (o botão flutuante e os CTA dependem dele), e depois bin/console cache:clear.
  • Webhook 403: token de verificação diferente entre a Meta e a extensão, ou App secret errado.
  • Mensagens de recuperação não enviadas: verifique que o scheduled-task:run e o messenger:consume estão a correr, que o módulo está ativo e que os templates HSM estão aprovados.
  • Produtos não sincronizados: consulte a página Catálogo (estados pending/synced/error) e os Registos, canal catalog.

RGPD

Nenhum dado é enviado a terceiros fora da Meta WhatsApp Cloud API. As conversas e os números são guardados localmente nas tabelas df_wac_ e eliminados na desinstalação.

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte