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

Apresentação

O DataFirefly WhatsApp Commerce Suite transforma o WhatsApp num canal de venda completo para o WooCommerce, através da API Meta Cloud oficial. O plugin inclui 4 módulos ativáveis de forma independente: sincronização do catálogo Meta Commerce, recolha de encomendas por conversa, recuperação de carrinho abandonado e ligação de pagamento assinada.

Instalação

1. Descarregue o dfwhatsappcommerce-1.0.1.zip a partir da sua conta de cliente DataFirefly.
2. No wp-admin, vá a Plugins → Adicionar → Carregar plugin, selecione o ZIP e clique em Instalar agora.
3. Ative a extensão. Aparece um novo menu WhatsApp na barra lateral da administração.

Na ativação, o plugin cria 5 tabelas SQL com prefixo dfwc_ (conversas, mensagens, carrinhos abandonados, registo do catálogo, registos) e agenda 3 eventos cron: processamento dos carrinhos a cada 15 minutos, limpeza diária dos registos, e sincronização do catálogo por lotes a cada hora.

Requisitos do lado da Meta

Antes de configurar o plugin, reúna estes 5 valores a partir da Meta Business Suite:

• Phone Number ID: WhatsApp → Configuração da API → o seu número
• WhatsApp Business Account ID: visível nas definições da conta WhatsApp Business
• Catalog ID: Commerce Manager → o seu catálogo → Definições
• Access Token permanente: crie um utilizador de sistema em Business Settings → Users → System Users, atribua-lhe as autorizações whatsapp_business_messaging e whatsapp_business_management, bem como catalog_management, e gere um token sem expiração
• App Secret: Meta for Developers → a sua aplicação → Definições → Geral

Configuração do plugin

1. Vá a WhatsApp → Definições.
2. Na secção Identificadores da Meta Cloud API, cole os 5 valores obtidos acima. O campo Webhook Verify Token vem pré-gerado automaticamente: só o altere se for necessário.
3. Indique o Número de WhatsApp apresentado no formato E.164 sem o sinal + (exemplo: 351912345678). É este número que será usado no botão flutuante e nos CTA.
4. Ative os módulos pretendidos na secção Módulos. Pode começar apenas pela sincronização do catálogo e ativar o resto progressivamente.
5. Guarde.

Configuração do webhook da Meta

O webhook permite que a Meta envie as mensagens recebidas e os estados de entrega para o seu site.

1. Abra WhatsApp → Painel no wp-admin: o Callback URL e o Verify Token aparecem aí, com botões de copiar.
2. No Meta for Developers, abra a sua aplicação → WhatsApp → Configuração → Webhook.
3. Cole o Callback URL e o Verify Token, e clique em Verificar e guardar.
4. Na lista de campos, subscreva messages.

O Callback URL tem a forma https://o-seu-site.com/wp-json/dfwc/v1/webhook. Cada pedido recebido é validado por assinatura HMAC SHA-256 com o seu App Secret: os pedidos sem assinatura ou com assinatura inválida são rejeitados.

Teste da ligação

A partir de WhatsApp → Painel:

• Testar a ligação à API: verifica os seus identificadores consultando o Phone Number ID e apresenta o número verificado.
• Enviar uma mensagem de teste: introduza um número no formato E.164 sem + e envie uma mensagem de texto de teste.

Módulo 1: sincronização do catálogo

Três modos disponíveis nas Definições:

• Tempo real: cada criação, alteração, mudança de stock ou eliminação de produto é imediatamente refletida no catálogo da Meta.
• Por lotes: as alterações são acumuladas e enviadas de hora a hora em lotes de 50.
• Manual: nada é enviado automaticamente e usa o botão de ressincronização.

Regras de mapeamento:

• Cada produto recebe um retailer_id da forma wc_{ID}.
• Os produtos variáveis não são enviados tal como estão: cada variação é enviada individualmente com o seu próprio preço, stock e imagem.
• Os produtos sem imagem são ignorados (exigência da Meta).
• O filtro dfwc_catalog_product_eligible permite excluir produtos por código, e o dfwc_catalog_product_data permite alterar os dados enviados.

Desde a versão 1.0.1, as Definições → Sincronização do catálogo propõem duas listas de categorias: Categorias a sincronizar (deixe vazio para enviar tudo) e Categorias a excluir. Os produtos sem imagem são registados com o estado skipped em vez de voltarem a ser selecionados em cada lote. No modo tempo real, cada sincronização é colocada em fila no Action Scheduler (fornecido com o WooCommerce): a gravação de um produto ou a redução de stock a cada encomenda nunca espera pela resposta da Meta. Pode acompanhar estas tarefas em WooCommerce → Estado → Ações agendadas, grupo dfwhatsappcommerce.

A página WhatsApp → Catálogo mostra os contadores de sucesso e de erro, o registo dos 50 últimos eventos, e o botão Lançar a ressincronização, que reenvia todos os produtos elegíveis em lotes de 100.

Módulo 2: encomenda por conversa

O módulo de conversa responde automaticamente às mensagens recebidas segundo uma máquina de estados: idle → browsing → selecting_qty → reviewing → awaiting_payment, mais um estado human_handoff.

Palavras-chave reconhecidas (francês e inglês na mesma conversa):

• menu ou catalogue: apresenta a lista interativa de produtos (até 30 elementos, ligados ao catálogo da Meta)
• panier ou cart: apresenta o conteúdo do carrinho com os botões Pagar / Continuar / Esvaziar
• commander, payer ou checkout: gera a ligação de pagamento
• humain, conseiller ou aide: transfere para um consultor (e-mail enviado para o endereço configurado)
• reset ou annuler: reinicia a conversa

Qualquer outro texto desencadeia uma pesquisa livre nos seus produtos. O carrinho do cliente é conservado na conversa e associado à conta WooCommerce dele se o número corresponder a um billing_phone existente.

A mensagem de boas-vindas e a mensagem alternativa são personalizáveis nas Definições. A página WhatsApp → Conversas lista todas as conversas e permite consultar cada thread numa vista ao estilo do WhatsApp Web.

Módulo 3: recuperação de carrinho abandonado

Funcionamento:

1. O plugin captura o carrinho dos visitantes (sessão do WooCommerce mais um cookie de recurso de 7 dias) e torna o campo de telefone obrigatório no checkout.
2. Passado o prazo de abandono (60 minutos por predefinição), parte o primeiro lembrete. Os lembretes 2 e 3 seguem-se conforme os seus próprios prazos (24 h e 72 h por predefinição, expressos em minutos nas Definições).
3. Cada lembrete usa um template HSM da Meta configurado por etapa. Se o template falhar, é tentada uma mensagem de texto simples como recurso.
4. O terceiro lembrete pode incluir um código promocional WooCommerce existente, aplicado automaticamente no checkout através da ligação de recuperação.
5. Quando o cliente finaliza a encomenda, o carrinho é marcado como recuperado e os lembretes param.

Criação dos templates HSM

Na Meta Business Suite → WhatsApp Manager → Modelos de mensagem, crie 3 templates (por exemplo dfwc_abandoned_cart_1, _2, _3) com:

• Um corpo com duas variáveis: {{1}} = primeiro nome do cliente, {{2}} = montante do carrinho
• Um botão de ação do tipo URL com uma variável {{1}} no fim do URL, a apontar para https://o-seu-site.com/wp-json/dfwc/v1/recover/{{1}}

Crie cada template nos idiomas dos seus clientes: o plugin deteta a locale e envia a versão certa. Depois de os templates serem aprovados pela Meta, indique os respetivos nomes nas Definições do plugin.

A página WhatsApp → Carrinhos abandonados mostra o total, os carrinhos em processo de recuperação, os carrinhos recuperados e a taxa de recuperação.

Módulo 4: pagamento e notificações

A ligação de pagamento gerada na conversa é um token assinado com HMAC (SHA-256, salt do WordPress mais o segredo do plugin) que contém o carrinho, a expiração e o identificador da conversa. Quando o cliente clica:

1. O token é validado e descodificado.
2. O carrinho WooCommerce é reconstruído no servidor.
3. O telefone do cliente é pré-preenchido no checkout.
4. O URL é limpo por redirecionamento.

A duração de validade da ligação é configurável (Definições → Pagamento). Uma ligação expirada mostra uma mensagem de erro a convidar a pedir outra pelo WhatsApp.

Notificações automáticas (ativáveis individualmente):

• Encomenda confirmada: enviada na passagem ao estado Processing, com número e total.
• Encomenda expedida: enviada na passagem a Completed, com o número de seguimento detetado a partir do Shipment Tracking, do AfterShip ou da meta _tracking_number, e um botão CTA de seguimento.
• Pagamento falhado: enviada na passagem a Failed, com um botão para tentar de novo o pagamento.

Botão flutuante e CTA

• Botão flutuante: ativável nas Definições, com posição à escolha entre os 4 cantos, designação personalizável e possibilidade de ocultar. O template templates/frontend/whatsapp-button.php pode ser substituído copiando-o para o-seu-tema/dfwhatsappcommerce/whatsapp-button.php.
• CTA na ficha de produto: botão «Encomendar pelo WhatsApp» por baixo do botão de adição ao carrinho, com mensagem pré-preenchida com o nome e a ligação do produto.
• CTA no carrinho: botão «Finalizar pelo WhatsApp» com o total do carrinho.
• CTA no checkout: ligação de ajuda discreta.
• Shortcode: [dfwc_whatsapp_button text="..." message="..."] para uma colocação manual em qualquer sítio.

Os cliques em todos estes elementos são enviados para o dataLayer (prefixo dfwc_) para o GA4 e o Google Tag Manager.

Registos e resolução de problemas

A página WhatsApp → Registos mostra todos os eventos com filtros por nível (debug a critical) e por canal (api, webhook, catalog, conversation, cart, payment). O nível de registo e a duração de retenção são configuráveis. Os registos também são visíveis em WooCommerce → Estado → Registos, nas origens dfwhatsappcommerce-*.

Problemas comuns:

• O webhook não é verificado: verifique que o seu site está em HTTPS com um certificado válido, que os permalinks não estão em modo «Simples», e que o Verify Token colado na Meta é igual ao das Definições.
• As mensagens recebidas não chegam: verifique que o campo messages está mesmo subscrito na configuração do webhook da Meta, e que o App Secret está correto (uma assinatura inválida rejeita silenciosamente os pedidos, o que é visível nos Registos, canal webhook).
• A sincronização do catálogo falha: verifique que o token de sistema tem a autorização catalog_management e que o Catalog ID corresponde mesmo ao catálogo associado à sua conta WhatsApp Business.
• Os lembretes não partem: verifique que o cron do WordPress funciona (o WP Crontrol permite visualizar o dfwc_process_abandoned_carts), e que os templates HSM estão aprovados pela Meta.

Desinstalação

A desativação do plugin conserva todos os dados. A remoção definitiva a partir da página de Plugins aciona o uninstall.php: as 5 tabelas são eliminadas e as opções e os eventos cron são apagados. As encomendas WooCommerce criadas através do WhatsApp nunca são tocadas.