# DataFirefly WhatsApp: documentação
> 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…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfwhatsapp/index.md), [en](https://www.datafirefly.com/en/documentation/dfwhatsapp/index.md), [es](https://www.datafirefly.com/es/documentation/dfwhatsapp/index.md), [de](https://www.datafirefly.com/de/documentation/dfwhatsapp/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfwhatsapp/index.md), [it](https://www.datafirefly.com/it/documentation/dfwhatsapp/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfwhatsapp/index.md)
- Índice:
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](mailto: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+