# 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…

- Página: <https://www.datafirefly.com/pt/documentation/dfwhatsappcommerce/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfwhatsappcommerce/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsappcommerce/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsappcommerce/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsappcommerce/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsappcommerce/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsappcommerce/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsappcommerce/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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

Requisitos: WordPress 6.2+, WooCommerce 8.0+, PHP 7.4+, uma conta WhatsApp Business com número verificado na Meta Business Suite, e um site acessível em HTTPS (obrigatório para o webhook da Meta).

## 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](https://business.facebook.com):

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

Nunca use o token temporário de 24 h apresentado no separador de arranque: vai expirar e estragar a sincronização. Crie sempre um token permanente de utilizador de sistema.

## 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](https://developers.facebook.com), 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.

Se a mensagem de teste não chegar apesar de a ligação estar OK, verifique que o número de destino enviou pelo menos uma mensagem para o seu número de WhatsApp Business nas últimas 24 h, ou use um template HSM aprovado: a Meta só autoriza mensagens de texto livres dentro da janela de serviço de 24 h.

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

As palavras-chave reconhecidas são as francesas e as inglesas fornecidas pelo plugin. Se os seus clientes escreverem em português, informe-os das palavras a usar (por exemplo no menu de boas-vindas), ou acrescente as suas próprias palavras-chave através dos filtros do plugin.

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

A Meta só aceita uma mensagem de texto livre nas 24 horas seguintes à última mensagem do cliente. Uma encomenda feita por um cliente que nunca escreveu no WhatsApp, ou que o fez há mais de 24 h, só pode ser notificada com um template HSM aprovado. Preencha portanto os três templates opcionais das **Definições → Pagamento**: **confirmação de encomenda** (variáveis {{1}} número, {{2}} total), **expedição** ({{1}} número, {{2}} número de seguimento) e **falha de pagamento** ({{1}} número, {{2}} ligação de pagamento). Sem template, o plugin envia um texto livre, que só chega dentro da janela de 24 h. A notificação de expedição só é enviada uma vez por número de seguimento, e as encomendas sem produto a expedir recebem uma confirmação em vez de uma mensagem de «a caminho».

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