Módulo Magento 2 – Perguntar sobre o produto

Kowal_ZapytajOProdukt é um módulo Magento 2 avançado para comunicação com o cliente na página de produto. Combina um formulário clássico de perguntas, uma FAQ organizada e um Assistente AI numa solução única e coerente.

Na prática, isto significa que a página de produto deixa de ser apenas um local de apresentação da descrição e dos parâmetros técnicos, passando a ser um ponto ativo de apoio às perguntas do cliente. O utilizador pode:

• fazer uma pergunta clássica sobre o produto,
• utilizar respostas prontas publicadas na FAQ,
• conversar com o Assistente AI, que responde no contexto do produto atualmente visualizado.

O módulo foi concebido para resolver dois problemas em simultâneo:

• operacional, ou seja, reduzir o número de perguntas repetitivas que chegam à equipa da loja,
• de produto, ou seja, construir uma base de conhecimento crescente e organizada, que ao longo do tempo melhora a qualidade das respostas.

Objetivo de negócio

Em muitas lojas online, uma parte significativa das perguntas dos clientes repete-se:

• se o produto é compatível com uma versão específica do Magento,
• se funciona sem um módulo adicional,
• como decorre a instalação,
• se suporta vários idiomas,
• se requer alterações personalizadas no template,
• como se comportará num determinado cenário de negócio.

Sem uma ferramenta dedicada de atendimento, estas perguntas:

• sobrecarregam o suporte,
• atrasam as decisões de compra,
• dispersam o conhecimento entre caixas de e-mail, tickets e conversas comerciais,
• não regressam à loja sob a forma de uma FAQ organizada.

Este módulo organiza esse processo. Primeiro recolhe perguntas e respostas, depois organiza-as numa FAQ e, numa fase seguinte, utiliza-as como contexto para o Assistente AI e para a camada de retrieval baseada no OpenAI Vector Store.

Ideia principal da solução

O módulo funciona por camadas.

Camada 1. Perguntas clássicas sobre o produto

Na página de produto, pode ativar o mecanismo padrão de envio de perguntas. O cliente envia uma questão e o administrador ou a equipa da loja recebe-a para tratamento posterior. É a forma de contacto mais simples e previsível.

Camada 2. FAQ

Perguntas e respostas repetitivas podem ser guardadas e publicadas como FAQ do produto. A FAQ pode ser apresentada como um separador ou como uma secção separada na página de produto. Assim, os utilizadores seguintes recebem a resposta sem terem de enviar uma nova pergunta.

Camada 3. Assistente AI

Acima ou abaixo da FAQ padrão surge um componente leve de conversação com AI. O utilizador pode:

• clicar numa das perguntas populares,
• introduzir a sua própria pergunta no campo Zapytaj Asystenta o ten produkt.,
• ver a resposta na mesma área de conversa.

O assistente não funciona como um chatbot geral da loja. Foi concebido como assistente de produto, o que significa que a resposta deve basear-se sobretudo em:

• dados do produto atual,
• FAQ publicadas,
• histórico da conversa atual,
• opcionalmente, resultados de retrieval do OpenAI Vector Store.

Âmbito funcional do módulo

1. Formulário Zapytaj o produkt

O módulo disponibiliza um mecanismo clássico de contacto com o cliente.

Elementos mais importantes:

• botão ou formulário Zapytaj o produkt na página de produto,
• suporte AJAX no frontend,
• gravação da pergunta na base de dados,
• possibilidade de envio de notificação por e-mail,
• opção de ativar o módulo globalmente ou apenas para produtos selecionados.

Esta solução continua a fazer sentido mesmo quando a loja já utiliza o Assistente AI. Nem todas as perguntas devem ser tratadas automaticamente. Algumas situações exigem uma resposta comercial, uma proposta individual ou confirmação pela equipa técnica.

2. FAQ na página de produto

A FAQ neste módulo não é um complemento de marketing, mas sim uma camada organizada de conhecimento sobre o produto.

O administrador pode:

• consultar perguntas guardadas,
• adicionar respostas,
• publicar registos selecionados,
• apresentá-los na página de produto.

A FAQ pode ser apresentada:

• como separador,
• como secção separada na página de produto.

O importante é que a FAQ não serve apenas o frontend. As perguntas e respostas publicadas também são utilizadas como um dos elementos mais importantes de contexto para o Assistente AI.

3. Assistente AI na página de produto

O Assistente AI é o elemento central da expansão do módulo.

O componente é incorporado na página de produto, por predefinição abaixo da galeria, e foi preparado para:

• funcionar de forma leve no frontend,
• não sobrecarregar desnecessariamente a primeira renderização da página,
• ser legível em desktop e mobile,
• adequar-se a futuras expansões.

O utilizador vê:

• o título da secção,
• um texto introdutório,
• um único campo de texto para fazer a pergunta,
• uma lista das perguntas mais populares,
• uma área de conversa, que se expande com as perguntas e respostas seguintes.

Na versão atual, o formulário também suporta:

• histórico de conversa no âmbito da sessão,
• perguntas populares clicáveis,
• feedback às respostas da AI,
• duas variantes cromáticas: clara e escura.

4. Perguntas populares

Por baixo do campo de texto podem ser apresentadas as perguntas mais populares sobre o produto.

Esta solução cumpre várias funções em simultâneo:

• acelera o início da conversa,
• mostra ao cliente o que os outros perguntam com mais frequência,
• permite utilizar respostas prontas da FAQ sem o custo de uma consulta ao modelo AI,
• melhora o UX e reduz o número de interações vazias.

A popularidade das perguntas já não se baseia apenas numa ordem manual. O módulo recolhe dados sobre cliques, perguntas feitas e feedback, e depois classifica a FAQ com base nesses dados.

5. Contexto das respostas da AI

O pressuposto de design mais importante foi garantir que a AI não responde desligada do produto.

A resposta pode ser construída com base em várias fontes:

• dados básicos do produto,
• short description,
• full description,
• atributos de produto selecionados,
• FAQ publicadas,
• histórico da conversa.

Além disso, o módulo permite limitar quais os atributos enviados para o modelo, permitindo evitar:

• sobrecarga do prompt,
• envio de dados desnecessários,
• custos de tokens demasiado elevados,
• transmissão acidental de conteúdos que não são úteis para o cliente.

6. Integração com OpenAI Responses API e Vector Store

Um dos elementos-chave da expansão é a integração com OpenAI Responses API.

Em cenários mais simples, o módulo pode funcionar no modo de contexto local do produto e da FAQ. Em implementações mais avançadas, suporta:

• file_search,
• vector_store_ids,
• filtragem por sku,
• filtragem por product_sku,
• filtragem por store_code,
• filtragem por content_type,
• limitação do número de resultados de retrieval,
• modo hybrid,
• modo retrieval-first.

Isto significa que a resposta da AI pode basear-se não só nos dados transmitidos diretamente a partir do Magento num determinado request, mas também em documentos previamente alimentados no Vector Store.

Na prática, isto oferece duas vantagens:

• menor custo, porque não é necessário enviar sempre todo o conjunto de dados para o modelo,
• melhor escalabilidade, porque o retrieval pode lidar com uma base de conhecimento maior do que um simples prompt com JSON local.

7. Integração com Kowal_AiProductFeed

O módulo foi preparado para trabalhar com Kowal_AiProductFeed.

Esta integração permite:

• sincronizar dados de produto com o OpenAI Vector Store,
• utilizar documentos do tipo product.core, product.faq, product.docs e outros,
• sincronizar um produto selecionado antes da conversa,
• limitar o retrieval a tipos de conteúdo específicos.

Esta abordagem é especialmente útil quando:

• as descrições de produto são longas,
• a FAQ é extensa,
• a loja suporta muitos produtos técnicos,
• os dados de produto estão em desenvolvimento contínuo.

8. Analítica e feedback

O módulo não termina na simples geração da resposta.

Também guarda dados que permitem avaliar se a solução funciona:

• número de cliques na FAQ,
• número de perguntas feitas,
• avaliações útil / não útil,
• histórico das conversas,
• metadados técnicos das respostas da AI,
• usage de tokens,
• payload do request e da resposta, se ativar o registo de diagnóstico.

Isto faz com que a implementação não seja uma caixa negra. A equipa pode analisar:

• quais as perguntas que surgem com mais frequência,
• se a AI utiliza retrieval,
• se as respostas são relevantes,
• quais os registos que vale a pena consolidar como FAQ,
• como o custo e a qualidade mudam após alterações no prompt ou na configuração.

9. Candidatos a FAQ e fluxo de trabalho administrativo

Uma das vantagens mais importantes do módulo é a possibilidade de transformar conversas em novas FAQ.

O processo é o seguinte:

1. Os clientes fazem perguntas.
2. O módulo guarda as conversas.
3. O mecanismo de análise identifica candidatos a FAQ.
4. O administrador revê os candidatos no painel.
5. Após aprovação, o candidato passa para a FAQ padrão do produto.

É um modelo de trabalho muito prático, porque o conhecimento não se perde no histórico das conversas. A cada nova iteração, a loja constrói uma camada de respostas melhor:

• para os clientes,
• para a FAQ,
• para o Assistente AI,
• para o retrieval futuro.

10. Segurança e controlo

O módulo foi preparado para que o seu funcionamento possa ser controlado.

A configuração inclui, entre outros:

• restrições de acesso para convidados,
• TTL das conversas,
• limites de consultas,
• sanitização dos dados de entrada,
• opções de registo de diagnóstico,
• configuração do reCAPTCHA,
• âmbito controlado dos dados enviados para o modelo.

Isto é importante, porque a implementação de AI na página de produto não deve significar perder o controlo sobre:

• custos,
• dados,
• qualidade das respostas,
• carga do frontend.

11. A quem se destina este módulo

O módulo funciona melhor em projetos onde:

• o catálogo é maior do que alguns produtos simples,
• os clientes fazem frequentemente perguntas sobre compatibilidade, configuração ou implementação,
• a equipa quer combinar uma FAQ clássica com uma camada moderna de AI,
• a empresa desenvolve documentação de produto e quer utilizá-la no retrieval,
• é importante controlar o que a AI sabe e de onde obtém as respostas.

É particularmente adequado para lojas que vendem:

• módulos Magento,
• produtos técnicos,
• soluções B2B,
• ferramentas que exigem implementação ou configuração,
• produtos em que o cliente espera uma resposta rápida e precisa ainda antes da compra.

12. Resumo

Kowal_ZapytajOProdukt já não é apenas um módulo para um formulário de contacto simples na página de produto.

É uma camada completa de comunicação de produto, que:

• recolhe perguntas,
• publica FAQ,
• responde através de AI,
• utiliza Vector Store,
• analisa conversas,
• e transforma-as numa base de conhecimento da loja cada vez melhor.

Desta forma, a página de produto torna-se um local de conversa real com o cliente, e não apenas uma página estática com descrição e preço.