Documentação do AI Personal Shopper

Instalação

Requisitos

Magento 2.4.x — testado em 2.4.9, compatível com versões anteriores 2.4.*. PHP 8.1–8.5. Compatível tanto com o tema Luma padrão quanto com o tema Hyvä (o widget do chat é renderizado em um Shadow DOM isolado, então fica idêntico nos dois, sem alterações de template). Depende do módulo gratuito codingrow/module-core, instalado automaticamente. Requer uma chave de API de pelo menos um provedor de IA (OpenAI, Anthropic, Google ou OpenRouter) — cobrada diretamente de você pelo provedor.

Passos de instalação

1. Adicione as credenciais que você receberá por e-mail a auth.json na raiz do seu projeto Magento:

   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }

2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-ai-personal-shopper
4. bin/magento module:enable Codingrow_AiPersonalShopper
5. bin/magento setup:upgrade && bin/magento setup:di:compile
6. Cole a sua chave de licença em Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key, salve e depois execute bin/magento cache:flush.

Configuração

Abra Admin → Stores → Configuration → Codingrow → AI Personal Shopper. Introduza a License Key, ponha Enable em Yes e depois reveja as Capabilities. Fornecedor, modelo e chave API não estão aqui: acrescenta-se uma IA no separador AI Models (Codingrow → AI Personal Shopper → AI Models).

Desinstalação

Defina Enable como No e salve para ocultar o widget imediatamente. Para remover o módulo por completo: bin/magento module:disable Codingrow_AiPersonalShopper e depois composer remove codingrow/module-ai-personal-shopper.

Configuração do provedor de IA

Escolher um provedor

O assistente funciona com qualquer um dos quatro provedores — você traz a sua própria chave de API, e o uso de IA é cobrado diretamente de você pelo provedor escolhido. OpenAI (ChatGPT/GPT) oferece a gama mais ampla; Anthropic (Claude) combina bem com um assistente que precisa manter-se fiel ao script; Google (Gemini) tem preços competitivos e é rápido; OpenRouter dá a você uma única chave para dezenas de modelos de diferentes provedores, útil para comparar custo e qualidade.

Obter uma chave de API da OpenAI

1. Faça login em platform.openai.com.
2. Acesse platform.openai.com/api-keys.
3. Clique em Create new secret key, dê um nome (ex.: "AI Personal Shopper") e copie-a imediatamente — ela é exibida apenas uma vez.
4. Acrescente-a como nova IA no separador AI Models (Codingrow → AI Personal Shopper → AI Models) com Provider definido como OpenAI, e depois use Load models para escolher o modelo.

Obter uma chave de API da Anthropic

1. Faça login em console.anthropic.com.
2. Acesse console.anthropic.com/settings/keys.
3. Clique em Create Key, dê um nome e copie o valor.
4. Acrescente-a como nova IA no separador AI Models (Codingrow → AI Personal Shopper → AI Models) com Provider definido como Anthropic, e depois use Load models para escolher o modelo.

Obter uma chave de API do Google

1. Faça login em aistudio.google.com com uma conta Google.
2. Acesse aistudio.google.com/app/apikey.
3. Clique em Create API key, escolha ou crie um projeto do Google Cloud e copie a chave.
4. Acrescente-a como nova IA no separador AI Models (Codingrow → AI Personal Shopper → AI Models) com Provider definido como Google, e depois use Load models para escolher o modelo.

Obter uma chave de API do OpenRouter

1. Faça login em openrouter.ai.
2. Acesse openrouter.ai/keys.
3. Clique em Create Key, dê um nome e copie o valor.
4. Acrescente-a como nova IA no separador AI Models (Codingrow → AI Personal Shopper → AI Models) com Provider definido como OpenRouter, e depois use Load models para escolher o modelo.

Load models

Assim que a chave de API estiver definida, clique em Load models abaixo do campo Model: o módulo consulta o próprio endpoint de listagem de modelos do provedor com a sua chave e preenche um menu suspenso com todos os modelos que a sua chave pode realmente usar — escolha na lista em vez de digitar um id. Um campo de texto manual continua disponível como alternativa para um id de modelo ainda não presente na lista. Um link logo abaixo do campo sempre aponta para a página correta para obter a chave do provedor selecionado no momento.

Calculadora de duracao do orcamento

O uso de IA e cobrado pelo provedor por token, entao a pergunta natural e quanto tempo um determinado orcamento vai durar. A tela de configuracao responde diretamente: logo abaixo das chaves API ha uma pequena calculadora de orcamento. Insira seu orcamento, o preco do modelo por milhao de tokens de entrada/saida (ha predefinicoes para Gemini Flash, OpenAI gpt-4o-mini, Claude Haiku 4.5 e Claude Sonnet 4.5) e o numero esperado de chats por dia. Ela mostra na hora o custo por chat e quantos dias o orcamento dura em um cenario otimista (chats curtos) e um pessimista (chats longos).

As suposicoes de tokens por chat sao iguais entre plataformas — so o preco do modelo muda — entao a comparacao e justa. Uma tabela de referencia mostra aproximadamente quanto dura um orcamento de €100 em cada modelo a cerca de 10 chats por dia. E apenas uma ajuda de planejamento; o custo real e sempre cobrado pelo provedor.

Qualidade e custo. O módulo já dá ao modelo tudo o que ele precisa para responder e ajudar — catálogo, pedidos, promoções, categorias, sinônimos e ferramentas. A qualidade das respostas depende então do modelo que você escolher: se não te satisfazem, basta experimentar outro modelo ou provedor. O custo decorre diretamente dessa escolha — mas um assistente desse tipo não precisa de um modelo caro, "de raciocínio" ou complexo: um econômico e rápido (categoria "flash"/"mini") é perfeitamente adequado.

Ajuste de IA e diagnóstico

Cada IA do pool traz as suas próprias definições, no seu cartão do separador AI Models — mais um limite que fica em Configuration:

• Max response tokens (no cartão da IA) — limita o comprimento de cada resposta; baixá-lo mantém as respostas curtas e os custos baixos.
• Temperature (no cartão da IA) — de respostas concentradas e previsíveis a formulações mais variadas. Deixado vazio não é enviado, que é o que as famílias de modelos mais recentes exigem.
• Max tool rounds (Stores → Configuration → … → Agent limits) — de 1 a 8, quantas vezes o modelo pode chamar as suas ferramentas (pesquisa, estado da encomenda, …) antes de ter de responder; mais alto permite respostas mais completas em vários passos, mais baixo é mais rápido e barato.
• Recent AI calls (diagnóstico) (separador AI Models) — as últimas 10 chamadas ao modelo com o resultado, o erro, a mensagem e a resposta: quando uma resposta não chega, vê-se o porquê num relance. Com o failover ativo nomeia a IA que realmente respondeu, não a primária.

Nota importante: a qualidade, a consistência e a proatividade das respostas dependem principalmente do modelo de IA que você escolhe, não apenas do módulo. Um modelo barato e rápido (um nível "flash"/"mini"/Haiku) custa pouco, mas é menos bom em curar a ordem dos cards, reduzir as opções a algumas poucas e propor combinações/cross-sell; um modelo mais capaz (por exemplo, Claude Sonnet, um modelo da classe GPT-4) segue essa lógica de forma muito mais confiável. Se as respostas não o satisfazem, a primeira coisa a tentar é mudar para um modelo mais forte — o custo muda de acordo, use a calculadora acima.

Guia do usuário

Capabilities

Cada capability é um interruptor independente em Capabilities. Desativar uma remove essa capacidade do agente imediatamente — nada é presumido ou inferido além do que está ativo:

• Pesquisa de produtos — busca em linguagem natural no catálogo em tempo real, retornada como cards de produto (ou cards de categoria quando o pedido é vago demais para um único produto).
• Status do pedido — consulta o status real do pedido para clientes logados, ou para visitantes que confirmam número do pedido + email.
• Promoções — o agente conhece os descontos ativos e pode mencioná-los ou filtrar por eles.
• Ler conteúdo de categoria — permite ao agente ler a descrição PageBuilder da própria categoria (get_category_info), para que guias de compra, tabelas de tamanhos e textos editoriais que você já escreveu nas páginas de categoria alimentem a resposta em vez de serem ignorados.
• Adicionar ao carrinho — permite ao cliente adicionar um produto diretamente de um card, com um seletor de quantidade, sem sair do chat.
• Entrada de voz — os clientes podem falar o pedido em vez de digitá-lo (microfone Web Speech).
• Sinônimos autoaprendidos — registra a correspondência entre uma palavra de busca que falhou e o termo do catálogo que acabou correspondendo.
• Tickets de suporte humano — permite ao agente abrir um ticket e passar para uma pessoa quando um pedido realmente precisa de um humano; ao desativar, o agente nunca vai propor abrir um ticket.
• Sugestões de cross-sell no encerramento — quando o cliente está finalizando, o agente pode adicionar um ou dois produtos complementares como sugestão final antes de se despedir. Desativado por padrão; ative-o apenas se quiser esse empurrãozinho no encerramento.

A experiência de produto

Tudo o que o cliente vê no chat — quais produtos, em que ordem e como os cards mudam à medida que a conversa avança — é conduzido pelo assistente, não por uma lista de resultados fixa.

• Cards curados e ao vivo — o assistente busca de forma ampla, depois escolhe quais produtos mostrar e em que ordem, direcionando para 2–3 opções fortes em vez de despejar uma parede de resultados. Os cards se atualizam em tempo real a cada turno: à medida que o cliente refina ("o na cor manga", "algo mais barato"), a grade é reconstruída para corresponder.
• Cards de categoria — quando um pedido é vago demais para um único produto ("um presente para casa, não sei o quê"), o assistente propõe categorias para explorar em vez de um beco sem saída.
• Respostas rápidas — botões de opção clicáveis oferecidos sob uma mensagem, para que o cliente avance com um toque em vez de digitar.
• Adicionar ao carrinho — um seletor de quantidade no próprio cartão confirma antes de adicionar. Desde a 2.2.0 também os produtos com tamanhos, cores ou vários artigos se compram dentro do chat: o assistente pede uma escolha de cada vez e ao carrinho vai a variante certa. A ficha de produto só é oferecida para as opções que o chat não consegue tratar, como uma gravação ou um ficheiro para carregar.
• Cards ricos — os cards de produto mostram nome, imagem, preço e qualquer desconto, além de um "Tell me more"; os cards de pedido mostram o rastreamento (transportadora + número) quando disponível.
• Persistência — a conversa sobrevive a uma atualização da página por 7 dias, e um botão Start over a limpa para começar do zero.

Tamanhos, cores e kits

Desde a 2.2.0 o carrinho do chat já não aceita apenas os produtos simples. Quando um produto tem escolhas a fazer, o assistente propõe-nas uma de cada vez dentro da conversa, e o produto vai para o carrinho com a variante certa.

• Configuráveis — primeiro o tamanho, depois a cor, depois a quantidade, pela ordem em que configurou os atributos no Magento. As combinações que não existem nem sequer são propostas.
• Agrupados (kits) — todos os artigos de uma vez, cada um com a sua quantidade; os que ficam a zero não vão para o carrinho.
• Bundle (conjuntos modulares) — uma escolha por cada opção, acessórios facultativos incluídos.

As escolhas são desenhadas como as configurou no Magento: as cores com o seu código hexadecimal real, os tamanhos com o valor grande e legível, as listas longas em menu suspenso. A quantidade aparece no último cartão do percurso. No computador tudo acontece no painel lateral, no telemóvel dentro do chat. Nos cartões de bundle e agrupados o preço é o intervalo real, e não 0,00 €.

As opções esgotadas continuam visíveis, em cinza. É o comportamento predefinido: esconder um tamanho esgotado faz o cliente acreditar que não o faz. O interruptor está em Stores → Configuration → Codingrow → AI Personal Shopper → Catalog Search → Show unavailable choices, greyed out; as que ainda podem ser encomendadas nunca são apagadas. Não confundir com Only in-stock products, que decide se o produto chega sequer a ser proposto.

Se um produto tiver opções personalizadas que o chat não consegue tratar (uma gravação para escrever, um ficheiro para carregar), o assistente di-lo e oferece a ligação para a ficha, em vez de abrir uma página sem explicações.

Sessões e reconhecimento de página

O assistente mantém o controle de com quem está falando e onde, para que a conversa pareça contínua e permaneça no produto certo.

• Rito de entrada — em vez de uma resposta pronta instantânea, o widget mostra um breve Connecting…, e então um operador com nome "entra no chat" após 10–20s e pergunta o nome do cliente. O tempo e a digitação são simulados, e o ritmo é configurável.
• Sessões — se o cliente voltar após mais de ~5 minutos, uma nova sessão começa sem pedir o nome novamente, marcada por uma linha divisória no chat; dentro de poucos minutos ela simplesmente continua.
• Contexto da página de produto — quando o chat é aberto a partir de uma página de produto, uma pergunta implícita ("fale-me sobre ele", "do que é feito?") se resolve para esse produto, vinculado nativamente por URL/url_key e robusto a redirecionamentos.
• Reconhecimento do carrinho — via get_cart o assistente pode tomar o que já está no carrinho como sinal de interesse — para sugerir combinações e evitar repropor o que já está lá — sem comentar sobre isso.
• Cross-sell no encerramento — quando a capacidade está ativada e o cliente terminou, ele adiciona um ou dois produtos complementares como sugestão final e depois se despede.

Assistente proativo

Desde a 2.2.0 o assistente pode tomar a iniciativa. Configura-se em Stores → Configuration → Codingrow → AI Personal Shopper → Proactive assistant e está tudo desligado no início: um vendedor que fala primeiro vende mais ou incomoda, e só você sabe como fala com os seus clientes. Em caso algum a janela do chat se abre sozinha: o assistente acende o ponto no botão e espera.

• Suggest pairings after an add to cart — Never (predefinido), only the first time in a visit ou every time. Quando o cliente coloca algo no carrinho ao percorrer a loja, o assistente prepara algumas combinações. De cada vez é uma chamada de IA, faturada pelo seu fornecedor. Aqui não há tempo de espera: arranca de imediato e aparece quando o modelo responde.
• Offer help after (seconds on the page) — 0 = nunca (predefinido). Se o cliente está há esse tempo numa página sem nunca ter aberto o chat, oferece-se uma mão. Não custa nada: a frase é escrita pelo widget. Nunca no carrinho nem no checkout.
• What it says — o texto do convite. Vazio = frase predefinida, traduzida em todas as línguas do módulo.

Funciona tanto em Hyvä como em Luma: o widget escuta os eventos que o tema já emite quando o carrinho muda, pelo que uma adição por AJAX sem recarregar a página também é detetada.

As conversas nascidas assim saltam o ritual do nome e chegam a Conversations sem nome: reconhecem-se pela coluna Origin (Customer, Assistant — after an add to cart, Assistant — offered help). Se o cliente responder e disser como se chama, o nome fica registado como em qualquer outro chat.

Branding e cores

Defina um Assistant name (exibido como o nome do operador, ex.: "Ana") e, opcionalmente, um Brand logo (altura fixa, para nunca deformar) ou um Brand text com o nome da sua empresa — exibidos no canto superior esquerdo do cabeçalho do chat. O nome do operador continua visível como uma sublinha com um indicador de presença ao vivo abaixo da marca, mesmo quando há um logotipo definido. Accent color controla o botão de abertura e os destaques no chat; Header/theme color (opcional) colore a barra do cabeçalho e os balões de mensagem do cliente — deixe em branco para reutilizar a accent color.

Botao de busca com IA

Quando a barra de busca fixa do modulo Live Search esta ativa, o AI Personal Shopper pode adicionar um segundo botao de lupa IA logo ao lado do campo de busca. Ao clicar, o chat do assistente abre; e se o cliente ja digitou algo no campo de busca, esse texto e enviado diretamente como primeira mensagem — assim uma busca que retorna resultados demais (ou zero) vira uma conversa guiada com um toque.

Ative em Stores → Configuration → Codingrow → AI Personal Shopper → Assistant & Branding com AI button in the search bar = Yes. E uma integracao suave: se o Live Search nao estiver instalado ou sua barra fixa estiver desligada, o botao simplesmente nao aparece — sem dependencia obrigatoria.

Sinônimos autoaprendidos

Quando ativada (Capabilities → Self-learning synonyms), o agente registra uma correspondência sempre que a palavra de busca de um cliente não corresponde diretamente ao catálogo, mas uma tentativa posterior sim — nomes regionais, dialeto, erros de digitação, sinônimos. Revise e edite o registro em Codingrow → AI Personal Shopper → Synonyms: uma tabela paginada e editável inline. Use Export CSV / Import CSV para fazer backup, editar em massa ou mover entre ambientes. O botão Inject into site search transfere todo o registro para os Search Synonyms nativos do Magento, para que a barra de busca do site também se beneficie — não só o chat. O agente também lê os seus Search Synonyms nativos curados manualmente, de modo que os dois sistemas se reforçam mutuamente.

Exemplo: um cliente busca "moletom com capuz" e o agente não encontra nada diretamente, mas uma tentativa posterior com "hoodie" corresponde — o par é registrado automaticamente, então a próxima busca por "moletom com capuz" se resolve na hora, e você pode injetá-lo na busca nativa com um clique.

Tickets de suporte humano

Quando ativada (Capabilities → Human support tickets), o agente propõe abrir um ticket se um cliente precisa de um humano e a conversa sozinha não resolve. Ele pede o e-mail (obrigatório) e, se útil, o número do pedido e um contato de telefone/WhatsApp, depois atribui um número de ticket — precedido pelo Ticket number prefix (padrão AIPS-), ex.: AIPS-000042 — e envia por e-mail a transcrição completa ao cliente, com cópia oculta para o endereço definido em Human support → Support email (BCC) (se deixado em branco, o e-mail vai só para o cliente). O texto do prazo de resposta mostrado ao cliente vem de Human support → Response time.

Os tickets aparecem na aba Tickets & Support: uma grade com View que abre os dados de contato e a transcrição completa, e uma coluna Closed by que registra quem fechou cada um — admin, cron ou customer. A ação Resolve fecha um ticket e pode substituir a notificação de fechamento padrão desse ticket, enviando ao cliente uma mensagem personalizada. Uma tarefa diária fecha automaticamente qualquer ticket que fique aberto além de Auto-close open tickets after (days) (registrado como closed_by = cron). O cliente também pode fechar ou cancelar o próprio ticket a partir do chat, mas apenas após uma verificação de propriedade — o número do ticket e o e-mail devem coincidir. O agente também classifica como Bug report as conversas que relatam um problema do site, para que os problemas cheguem à sua equipe sem precisar de um ticket de suporte.

Exemplo: um cliente escreve "Preciso falar com alguém sobre meu pedido". O agente pede o e-mail (e, se útil, o número do pedido e um contato de telefone/WhatsApp), atribui um número de ticket como AIPS-000042 e envia por e-mail a transcrição completa ao cliente, com cópia oculta para o seu endereço de suporte. Sua equipe resolve pela aba Tickets & Support — enviando opcionalmente ao cliente uma mensagem personalizada — ou ele fecha automaticamente (closed_by = cron) depois de ficar inativo pelo número de dias configurado.

Segurança e antiabuso

Como cada resposta de IA custa uma chamada de API real, o widget é protegido por uma defesa em camadas que detém sondagens, scanners, tentativas de injeção e de prompt-injection e mensagens de baixo valor antes que cheguem ao modelo — a custo zero.

• Limites por IP — um limite de rajada de 15 requisições / 60s, 300 requisições por dia, no máximo 30 novos chats por dia e 60 turnos por conversa.
• Disjuntor global — um teto para toda a loja de cerca de 5.000 chamadas de IA por dia protege o orçamento contra um ataque distribuído.
• Token de prova de widget — o widget prova que passou pelo rito de entrada real; o interruptor Require widget token (Security & anti-abuse) o impõe e rejeita chamadas forjadas ao endpoint.
• Registro completo — cada evento bloqueado é registrado com IP, user-agent e motivo, para que o abuso permaneça visível.
• Watchdog do provider — se o provider de IA começar a falhar (sem crédito, chave errada), um watchdog envia um e-mail para você, para que uma interrupção silenciosa não passe despercebida.

Ler conversas

Codingrow → AI Personal Shopper → Conversations lista cada conversa, classificada automaticamente como Shopping, Support, Bug report, Possible spam ou Other, paginada e filtrável por tipo. A ação View abre o thread completo — cada mensagem do cliente e do assistente, incluindo os cards de produto propostos em cada turno — somente leitura. As conversas podem ser excluídas individualmente ou em massa; conversas mais antigas do que a retenção configurada são removidas por uma tarefa diária (relatos de bug são excluídos da limpeza automática).

Exemplo: uma conversa em que o cliente descreve um erro no checkout é classificada automaticamente como Bug report, para que sua equipe a veja no console sem que ninguém precise enviar um e-mail.

Licença

A licença é emitida para um domínio e pode ser uma chave de módulo único (AI Personal Shopper) ou uma chave de assinatura Codingrow (todos os módulos). Sem licença válida, o widget do chat não é renderizado. A tua licença cobre a versão atual mais 1 ano de atualizações e suporte; podes continuar a usar para sempre as versões cobertas e renovar o suporte (−35%) para atualizar para versões mais recentes.