PS PrestaShop PrestaShop Iniciante

DataFirefly WhatsApp: documentação

Guia completo de instalação, configuração e utilização do módulo DataFirefly WhatsApp para PrestaShop 8 e 9.

Atualizado Versão do módulo 1.0.0

Bem-vindo à documentação do módulo DataFirefly WhatsApp. Este guia cobre tudo o que precisa para instalar, configurar e tirar o máximo partido do seu botão flutuante de WhatsApp multiagente no PrestaShop 8 e 9.

Instalação

O módulo instala-se como qualquer módulo PrestaShop, em poucos cliques.

Pré-requisitos

  • PrestaShop 8.0.x ou 9.0.x
  • PHP 8.0 ou superior (8.1+ recomendado)
  • MySQL 5.6+ ou MariaDB 10.3+
  • Pelo menos um número de WhatsApp (pessoal ou Business)

Passos da instalação

  1. Descarregue o ficheiro dfwhatsapp-v1.0.0.zip da sua área de cliente DataFirefly
  2. No back-office do PrestaShop, vá a Módulos > Gestor de módulos
  3. Clique em Carregar um módulo, no canto superior direito
  4. Selecione o ficheiro ZIP e confirme
  5. Clique em Instalar quando o módulo aparecer
  6. Clique em Configurar para abrir o ecrã de definições

Dica: o módulo cria automaticamente 6 tabelas na sua base de dados e acrescenta duas entradas de menu em Vender > Catálogo, para a gestão dos agentes e para o painel de estatísticas.

Configuração geral

A página de configuração do módulo está organizada em 6 separadores, para poder definir tudo sem se perder.

Separador Geral

  • Ativar o módulo: interruptor principal, que desativa o botão em toda a loja
  • Modo de seleção de agente: rotativo, aleatório, primeiro disponível ou manual
  • Ativar o seguimento: necessário para alimentar o painel de estatísticas
  • Código QR em computador: mostra um código QR em vez de abrir o WhatsApp Web nos postos fixos

Separador Aspeto

  • Posição: quatro cantos possíveis (inferior direito, inferior esquerdo, superior direito, superior esquerdo)
  • Cor: por predefinição, o verde do WhatsApp #25D366
  • Tamanho do ícone: em píxeis (60 por predefinição)
  • Deslocamento X / Y: distância à margem do ecrã
  • Animação: pulsar, saltar, tremer ou nenhuma
  • Etiqueta de texto: etiqueta opcional apresentada junto do botão

Separador Mensagens

Uma mensagem pré-preenchida distinta para cada tipo de página (produto, carrinho, categoria, CMS, encomenda, página inicial), traduzida nos 4 idiomas incluídos.

Separador Horário

  • Modo fora de horas:
    • hide: o botão desaparece por completo
    • show_offline: o botão continua visível a cinzento, com uma mensagem de espera
    • callback: um formulário de contacto substitui a conversa direta
  • Mensagem fora de horas: texto apresentado quando todos os agentes estão offline

Separador RGPD

  • Ativar o consentimento: mostra um texto de consentimento antes de cada abertura do WhatsApp
  • Texto do consentimento: personalizável por idioma

Separador Exclusões

  • Páginas excluídas: lista de controladores (por exemplo, checkout, identity)
  • Categorias excluídas: IDs de categorias separados por vírgulas
  • Produtos excluídos: IDs de produtos separados por vírgulas

Gestão dos agentes

É o coração do módulo: é aqui que acrescenta as pessoas que vão receber as mensagens de WhatsApp.

Acrescentar um agente

  1. Vá a Vender > Catálogo > Agentes WhatsApp
  2. Clique em Adicionar
  3. Preencha:
    • Nome: nome apresentado ao cliente (por exemplo, «Alex»)
    • Telefone: em formato internacional e sem espaços (por exemplo, 351912345678 para Portugal)
    • Departamento: livre (Apoio, Vendas, Técnico e outros)
    • Avatar: imagem opcional (png, jpg, svg, webp)
    • Posição: ordem de apresentação no modo manual
    • Função: texto traduzido nos 4 idiomas (por exemplo, «Apoio técnico»)
    • Mensagem personalizada: substituição opcional das mensagens contextuais

O indicativo de Portugal é o 351, sem o sinal de mais nem espaços: um número móvel português escreve-se 351912345678. Um erro no indicativo é a causa mais frequente de uma conversa que nunca chega.

Configurar os horários de um agente

No próprio formulário do agente, uma tabela semanal permite definir:

  • Vários períodos por dia (por exemplo, das 9h00 às 12h30 e das 14h00 às 18h30)
  • Um dia vazio significa agente offline nesse dia
  • Um agente sem qualquer período definido é considerado sempre disponível (modo 24/7)

Os horários seguem a hora do servidor. Confirme que o fuso está em Europe/Lisbon: se o servidor estiver em UTC, no horário de verão os seus agentes ficam disponíveis uma hora mais cedo do que devia. E se atende clientes nos Açores, note que a região tem menos uma hora do que o continente.

Acrescentar uma exceção (feriado, férias)

  1. No formulário do agente, secção Exceções
  2. Preencha uma data de início e uma data de fim
  3. Acrescente uma designação opcional (por exemplo, «Férias de verão»)

Nota: também pode acrescentar exceções globais, aplicáveis a todos os agentes, deixando o ID do agente a 0 na base de dados. É por aqui que introduz os feriados portugueses, que não estão pré-carregados: 1 de janeiro, Carnaval quando o observa, Sexta-feira Santa, Páscoa, 25 de abril, 1 de maio, Corpo de Deus, 10 de junho, 15 de agosto, 5 de outubro, 1 de novembro, 1 e 8 de dezembro e 25 de dezembro, mais os feriados municipais e os das regiões autónomas.

Variáveis contextuais

As mensagens pré-preenchidas suportam 12 variáveis, substituídas na hora consoante a página onde o cliente estiver:

  • {product_name}: nome do produto (ficha de produto)
  • {product_url}: URL completo do produto
  • {product_price}: preço formatado com a moeda
  • {product_ref}: referência do produto
  • {customer_name}: nome do cliente, se tiver sessão iniciada
  • {cart_id}: ID do carrinho
  • {cart_total}: total do carrinho formatado
  • {cart_summary}: lista dos artigos do carrinho
  • {order_ref}: referência da encomenda
  • {order_total}: total da encomenda
  • {category_name}: nome da categoria atual
  • {shop_name}: nome da loja

Modos de encaminhamento dos agentes

Rotativo

O módulo alterna entre os agentes disponíveis a cada nova abertura, equilibrando naturalmente a carga.

Aleatório

É sorteado um agente entre os que estão disponíveis. É útil quando a equidade entre agentes não é crítica.

Primeiro disponível

É selecionado o primeiro agente da lista (segundo a posição) que esteja disponível nesse momento.

Manual

Aparece ao cliente uma janela com a lista dos agentes disponíveis (avatar, nome, função, estado). O cliente escolhe o seu interlocutor.

Estatísticas e RGPD

O painel

Acessível em Vender > Catálogo > WhatsApp Analytics, mostra-lhe:

  • Total de cliques no período
  • Número de visitantes únicos (por hash do IP)
  • Rácio de cliques por visitante
  • Distribuição por dia, por tipo de página e por agente
  • Os 20 produtos que mais desencadeiam conversas

Proteção de dados

Conformidade com o RGPD:

  • Consentimento explícito apresentado antes de cada abertura do WhatsApp
  • IP dos visitantes com hash em SHA-256, com um sal próprio da sua loja (PS_SHOP_DOMAIN e _COOKIE_KEY_)
  • Sem armazenamento direto de dados pessoais
  • Sem depósito de cookies de terceiros

Continuando: a conversa em si passa a decorrer no WhatsApp, que é a Meta. As mensagens dos seus clientes, os números de telefone e o histórico ficam nos servidores dela, fora do seu controlo. Se usa o WhatsApp como canal de apoio, inscreva-o no seu registo de atividades de tratamento, indique-o na sua política de privacidade e evite pedir por ali dados sensíveis ou dados de pagamento. O texto de consentimento do módulo é o sítio certo para avisar o visitante de que está prestes a sair para uma plataforma de terceiros.

Código QR em computador

Nos computadores de secretária, em vez de abrir o WhatsApp Web (que obriga o cliente a ler sistematicamente um código QR), pode ativar o modo de código QR direto:

  • O módulo gera um código QR com a ligação wa.me e a mensagem pré-preenchida
  • O cliente lê o código com o telemóvel
  • O WhatsApp abre diretamente no telemóvel, com a mensagem pronta a enviar

Este modo mantém a conversa no canal preferido do cliente, sem atrito adicional.

Formulário de contacto

Quando todos os seus agentes estão offline e escolheu o modo callback:

  1. O cliente vê um formulário em vez da conversa habitual
  2. Preenche o nome, o telefone e uma mensagem opcional
  3. O pedido fica guardado na tabela ps_dfwhatsapp_callback, com o estado pending
  4. Pode consultar os pedidos por phpMyAdmin ou construir um relatório próprio

Ao contrário do resto do módulo, este formulário guarda mesmo dados pessoais na sua base: nome e telefone. Defina uma duração de conservação e elimine os pedidos já tratados, em vez de os deixar acumular indefinidamente na tabela.

Multi-idioma

O módulo é fornecido com 4 idiomas completos: francês, inglês, espanhol e alemão. Todos os textos visíveis do lado do cliente estão traduzidos:

  • Mensagens contextuais por página
  • Texto de consentimento de RGPD
  • Mensagem da janela de boas-vindas
  • Designações dos agentes (função, estado)
  • Interface do formulário de contacto
  • Mensagem fora de horas

Também pode definir uma função e uma mensagem personalizada diferentes para cada idioma e cada agente, diretamente no formulário do agente, mudando o separador de idioma.

O português não está entre os quatro idiomas fornecidos. Antes de publicar numa loja portuguesa, traduza em Internacional > Traduções pelo menos o texto de consentimento, a mensagem fora de horas e o formulário de contacto, e preencha as mensagens contextuais e as funções dos agentes em português nos campos por idioma. Um botão de conversa que fala francês afasta mais clientes do que traz.

Compatibilidade

  • PrestaShop 8.0.x, 8.1.x, 8.2.x e 9.0.x
  • PHP 8.0 a 8.3
  • Multiloja: sim (configurações distintas por loja)
  • Multi-idioma: sim (não exige Polylang)
  • Cache: compatível (Hummingbird, LSCache, Redis)
  • Overrides de classes do núcleo: nenhum

Resolução de problemas

O botão não aparece

  1. Confirme que o módulo está ativo em Geral
  2. Confirme que existe pelo menos um agente com o estado Ativo
  3. Confirme que a página atual não está na lista de exclusões
  4. Limpe a cache do PrestaShop (Parâmetros avançados > Desempenho)
  5. Limpe a cache do navegador (Ctrl+Shift+R)

O clique no botão não faz nada

  1. Abra a consola do navegador (F12) e confirme que não há erros de JavaScript
  2. Confirme que nenhum outro módulo está a bloquear o JS deste módulo
  3. Confirme que o dfwhatsapp.js está mesmo carregado no HTML

As estatísticas não aumentam

  1. Confirme que o seguimento está ativo em Geral
  2. Confirme que nenhum bloqueador de publicidade do lado do cliente está a filtrar o URL module/dfwhatsapp/track
  3. Consulte a tabela ps_dfwhatsapp_click para ver se os eventos estão a chegar

Erro SQL «LIMIT 1 LIMIT 1»

Corrigido na versão 1.0.1. Atualize o módulo para a última versão a partir da sua área de cliente DataFirefly.

Suporte e atualizações

  • Suporte por e-mail: hello@datafirefly.com
  • Atualizações incluídas durante 12 meses, na sua área de cliente
  • Compatibilidade PS 8 e PS 9 garantida sem custos adicionais

Registo de alterações

1.0.0, 13 de maio de 2026, lançamento

  • Versão inicial pública
  • Multiagente com quatro modos de encaminhamento
  • Horário semanal por agente, com exceções
  • Janela de boas-vindas, código QR em computador e formulário de contacto
  • Consentimento de RGPD nativo e estatísticas com hash do IP
  • Quatro idiomas: FR, EN, ES e DE
  • Compatível com PrestaShop 8.0+ e 9.0+
Esta página foi útil?

Ainda com dúvidas? Contacte o suporte