AI Email Template Generator para Magento 2
- Compatibilidade
- 2.4.9, 2.4.8, 2.4.7, 2.4.6, 2.4.5, 2.4.4, 2.4.3, 2.4.2, 2.4.1, 2.4.0, 2.3.7, 2.3.6, 2.3.5, 2.3.4
Descrição / AI Email Template Generator para Magento 2
MAGENTO 2 · MODELOS DE E-MAIL · IA · FILA MAGENTO
Prepare uma nova versão do e-mail no editor nativo do Magento.
Kowal AI Email Template Generator
Adicione um prompt, um projeto de referência e recursos gráficos ao modelo guardado. Encomende a geração em segundo plano, reveja o resultado e aplique-o ao nome, assunto, conteúdo e estilos do modelo.
JSON e validação · Histórico de tarefas · Controlo da aplicação do resultado
COMO FUNCIONA NA PRÁTICA
01 · Descreve a alteração esperada
Adiciona um prompt, uma referência e recursos da marca.
02 · A fila processa o pedido
O consumer executa a tarefa e guarda o resultado ou o erro.
03 · Verifica e aplica o projeto
Valida as variáveis, o aspeto e o conteúdo da mensagem.
O que ganha a sua loja?
Conheça as funcionalidades, a utilização e as definições do módulo.
Conheça o módulo
AI Email Theme Generator expande a gestão de modelos de e-mail no Magento 2 com geração assistida por IA. O módulo adiciona um processo prático para melhorar os modelos transacionais nativos do Magento diretamente a partir do painel de administração, sem substituir o sistema padrão de modelos de e-mail.
Os administradores podem gerar, reconstruir, corrigir ou desenvolver modelos de e-mail Magento existentes utilizando o ChatGPT através da OpenAI API. O resultado da geração regressa como dados estruturados e pode ser guardado nos campos nativos do Magento:
- Template Name
- Template Subject
- Template Content
- Template Styles
O processo é controlado, auditável e assíncrono. Cada pedido de IA é tratado pela fila do Magento e acompanhado como uma tarefa separada com informação sobre estado, histórico, erros, payload do pedido, payload da resposta e resultado gerado.
Valor para o negócio
Os e-mails transacionais do Magento são um ponto de contacto importante com o cliente, mas o seu aspeto predefinido costuma ser muito genérico e exige trabalho manual em HTML/CSS para o adaptar à marca. AI Email Theme Generator reduz o tempo necessário para preparar melhores modelos de e-mail, mantendo o resultado na infraestrutura nativa do Magento.
O módulo é útil para:
- renovar as mensagens transacionais predefinidas do Magento,
- criar layouts de e-mail alinhados com a identidade da marca,
- melhorar assuntos e conteúdos das mensagens,
- adaptar modelos a um projeto gráfico fornecido,
- preservar variáveis e diretivas do Magento,
- trabalhar num processo repetível que pode ser revisto e controlado.
Geração por IA no editor nativo Email Templates
O módulo expande a interface administrativa padrão do Magento:
Marketing > Communications > Email Templates
Um modelo guardado recebe campos de IA adicionais diretamente no editor padrão de modelos de e-mail do Magento. O administrador pode introduzir um prompt, adicionar um projeto de referência opcional, preparar recursos gráficos e solicitar a geração com ChatGPT.
Resposta estruturada da IA
O resultado da IA é esperado como JSON e mapeado para os campos nativos do Magento:
{ 'template_name': 'New Order Confirmation - Guest', 'template_subject': 'Your order confirmation', 'template_content': '', 'template_styles': '/* CSS */', 'warnings': [], 'change_summary': 'Updated layout and improved copy.', 'variables_used': ['order.increment_id', 'store.frontend_name']}
Desta forma, o resultado é previsível e mais fácil de validar antes de guardar.
Processamento assíncrono
A geração não é executada durante o carregamento da página administrativa. O módulo cria uma tarefa na fila e processa-a em segundo plano com Magento Message Queue.
Isto evita longas esperas no painel de administração e dá à equipa uma visão clara de cada pedido de geração.
Histórico de tarefas e tratamento de erros
As tarefas de geração estão disponíveis em:
Marketing > Communications > AI Email Generation Jobs
Cada tarefa mostra:
- estado atual,
- número de tentativas,
- modelo utilizado,
- modelo associado,
- prompt,
- resultado gerado,
- payload do pedido e da resposta,
- avisos,
- mensagem de erro,
- histórico de estados.
As tarefas falhadas podem ser repetidas, as tarefas pendentes podem ser canceladas e os resultados concluídos podem ser aplicados manualmente, se a gravação automática do resultado estiver desativada.
Projeto de referência opcional
Os administradores podem adicionar um ficheiro de referência, por exemplo uma imagem, HTML ou ficheiro de texto. O ficheiro é anexado ao contexto da IA e pode ser usado para gerar um modelo alinhado com o conceito gráfico escolhido.
Recursos gráficos estruturados para e-mail
O editor nativo de modelos de e-mail também pode guardar recursos de IA atribuídos a um modelo específico:
- logótipo,
- imagem de cabeçalho,
- lista dinâmica de banners,
- lista dinâmica de ícones.
Cada recurso pode ter uma etiqueta, texto alternativo, URL de destino e ordem de ordenação. As linhas de banners e ícones podem ser adicionadas dinamicamente no formulário.
Durante a geração, o módulo envia para a IA a secção assets com URLs frontend públicos agrupados por finalidade. Assim, o ChatGPT sabe que imagem é o logótipo, qual pertence ao cabeçalho, que ficheiros são banners e quais são ícones.
Esta abordagem oferece um layout de e-mail mais previsível do que enviar uma única imagem de referência genérica.
Prompt técnico configurável
O módulo inclui um prompt técnico global usado em cada pedido de geração. O prompt contém regras técnicas constantes, por exemplo:
- preservar as diretivas Magento,
- não inventar variáveis indisponíveis,
- não adicionar JavaScript,
- manter compatibilidade com clientes de e-mail,
- devolver apenas uma resposta JSON.
Isto separa as instruções técnicas do prompt de negócio escrito para um único modelo.
Instalação exclusivamente via Composer
O módulo é preparado como um pacote Composer para Magento:
kowal/module-ai-email-theme-generator
Destina-se a ser instalado como pacote de vendor, e não copiado manualmente para app/code.
Preparado para traduções
O módulo está implementado em inglês e todos os textos visíveis estão preparados para o mecanismo i18n do Magento através de helpers de tradução ou etiquetas e comentários XML traduzíveis.
Redesign de e-mails transacionais
A IA pode ser usada para modernizar mensagens predefinidas do Magento, tais como:
- confirmação de nova encomenda,
- confirmação de expedição,
- mensagem com fatura,
- mensagem com nota de crédito,
- mensagens da conta de cliente,
- reposição de palavra-passe.
Adaptação à marca
O administrador pode fornecer um prompt e um projeto de referência para que o modelo gerado corresponda ao tom de comunicação da loja, às cores, às expectativas tipográficas e ao estilo do layout.
Apoio ao trabalho do developer
Os developers podem usar o módulo para gerar a primeira versão do modelo e, em seguida, verificar o resultado, validar as diretivas Magento e refinar o HTML/CSS final.
Experimentação controlada
Como cada pedido é guardado como tarefa, a equipa pode comparar prompts, modelos, resultados, avisos e erros sem perder o histórico.
Segurança e controlo
AI Email Theme Generator foi criado para apoiar administradores e developers, e não para contornar a validação nem o processo de revisão dos modelos Magento.
O módulo suporta:
- armazenamento encriptado da API key,
- aplicação automática configurável do resultado,
- processamento através de fila,
- acompanhamento dos estados das tarefas,
- ações retry e cancel,
- eliminação individual e em massa de tarefas,
- validação dos campos obrigatórios da resposta da IA,
- bloqueio de tags
scriptno conteúdo gerado, - recursos gráficos estruturados com URLs frontend,
- armazenamento opcional dos payloads de pedidos e respostas.
Em ambientes de produção, recomenda-se desativar a aplicação automática do resultado até a equipa verificar a qualidade dos modelos gerados para os seus prompts e casos de utilização.
Resumo
AI Email Theme Generator introduz a geração de modelos de e-mail assistida por IA no painel Magento 2, mantendo simultaneamente o workflow nativo de Email Templates. O módulo ajuda a melhorar mais rapidamente as mensagens transacionais, mantém a auditabilidade através de tarefas em fila e dá aos developers controlo sobre os prompts, o formato da resposta e a forma de aplicação do resultado.
É necessário um consumer para executar a tarefa
A configuração encontra-se em Stores → Configuration → Services → AI Email Theme Generator. Introduza a API key, escolha o modelo e defina timeouts, retry e a política de aplicação do resultado.
As tarefas são executadas pelo consumer kowal.ai_email.generate.consumer. Em produção, garanta o seu funcionamento através do gestor de processos utilizado. Guardar o pedido na fila não significa que a geração tenha sido concluída.
A revisão manual é a política predefinida
O módulo e a aplicação automática do resultado estão desativados por predefinição. O validador verifica os campos obrigatórios da resposta, os seus tipos, nome, assunto e conteúdo não vazios, e bloqueia a tag script.
Isto não substitui a verificação das diretivas, da disponibilidade das variáveis e do aspeto em clientes de e-mail. Teste o modelo no tipo de mensagem correto antes de o atribuir ao envio em produção.
Referências, gráficos e histórico
O limite predefinido para o ficheiro de referência é 5 MiB, e as extensões permitidas são png, jpg, jpeg, webp, html, htm e txt. Os recursos de logótipo, cabeçalho, banners e ícones são enviados com os seus URLs públicos.
O pedido envia conteúdo e contexto para o serviço de IA. A conservação de payloads é configurável; o histórico permite verificar o resultado, avisos e erros. O módulo gera modelos, não executa campanhas nem envios de marketing.
Instalação via Composer
Pacote kowal/module-ai-email-theme-generator, módulo Kowal_AiEmailThemeGenerator. Depois de configurar o acesso ao repositório Kowal, instale o pacote, ative o módulo, atualize o Magento e limpe a cache. Em produção, inclua a compilação e a implementação de conteúdo estático de acordo com o processo da loja.
Da configuração ao resultado
1. Descreve a alteração esperada
Adiciona um prompt, uma referência e recursos da marca.
2. A fila processa o pedido
O consumer executa a tarefa e guarda o resultado ou o erro.
3. Verifica e aplica o projeto
Valida as variáveis, o aspeto e o conteúdo da mensagem.
Atualização da confirmação de encomenda
Carrega o modelo nativo, adiciona o logótipo e uma instrução sobre o estilo da marca. A IA prepara uma proposta que preserva as diretivas indicadas.
Antes de usar, verifica a pré-visualização, os dados reais da encomenda e a visualização em clientes de e-mail. Pode aplicar o resultado manualmente.
Otimize a preparação de modelos transacionais
Quer adaptar o módulo à sua loja? Peça a implementação do Kowal AI Email Template Generator e discuta a configuração ou as extensões necessárias.
Mais informação
| Addtocart Description | Veja a DEMO do módulousername: emails |
|---|---|
| Compatibilidade com o modelo | Luma / Blank, KOWAL |
Manual de instalação do módulo
Instruções de instalação e configuração
1. Requisitos
O módulo destina-se ao Magento 2 e a uma instalação gerida pelo Composer.
Requisitos:
- projeto Magento 2 gerido pelo Composer,
- versão PHP compatível com a instalação Magento utilizada,
- acesso ao Magento CLI,
- OpenAI API key,
- processo Magento Message Queue consumer em funcionamento.
Pacote do módulo:
kowal/module-ai-email-theme-generatorNome do módulo Magento:
Kowal_AiEmailThemeGenerator2. Instalação
Adicione o repositório Composer:
Os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença, serão enviados por e-mail após a compra. Também estão disponíveis no painel de cliente após iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do Magento.
composer config repositories.kowal composer https://repo.kowal.storeConfigure os dados de acesso ao repositório Composer Kowal:
composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'Instale o módulo:
composer require kowal/module-ai-email-theme-generatorAtive o módulo:
bin/magento module:enable Kowal_AiEmailThemeGeneratorExecute a atualização do Magento:
bin/magento setup:upgradeLimpe a cache:
bin/magento cache:flushPara o modo de produção, execute os comandos padrão de implementação utilizados no projeto, por exemplo:
bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush3. Queue Consumer
A geração por IA é processada de forma assíncrona através da Magento Message Queue.
Execute o consumer manualmente:
bin/magento queue:consumers:start kowal.ai_email.generate.consumerEm ambientes de produção, configure o consumer com supervisor, systemd ou outro gestor de processos utilizado pelo alojamento.
O módulo cria tarefas no painel de administração, mas o pedido para a IA não será processado enquanto o consumer não estiver em execução.
4. Permissões do administrador
O módulo adiciona recursos ACL:
Kowal_AiEmailThemeGenerator::rootKowal_AiEmailThemeGenerator::jobsKowal_AiEmailThemeGenerator::generateKowal_AiEmailThemeGenerator::retryKowal_AiEmailThemeGenerator::cancelKowal_AiEmailThemeGenerator::applyKowal_AiEmailThemeGenerator::deleteKowal_AiEmailThemeGenerator::settingsPara que o administrador possa usar o módulo, atribua os recursos adequados em:
System > Permissions > User RolesPara acesso completo, permita o recurso principal AI Email Generation e todos os recursos subordinados.
5. Localização da configuração
Aceda a:
Stores > Configuration > AI Email Generation > AI Email Theme GeneratorA secção de configuração contém o grupo:
General Settings6. Campos de configuração
Enabled
Tipo: Yes/No
Predefinição: No
Ativa ou desativa as funcionalidades do módulo.
Quando definido como No:
- o módulo não deve criar tarefas de geração por IA,
- a ação de geração é bloqueada,
- o administrador deve primeiro configurar o módulo.
Defina Yes apenas depois de preparar a API key e iniciar o queue consumer.
API Provider
Tipo: Select
Predefinição: OpenAI
Define o fornecedor de IA utilizado pelo módulo.
A implementação atual suporta:
OpenAIO campo existe para permitir adicionar novos providers no futuro sem alterar o workflow do administrador.
OpenAI API Key
Tipo: campo oculto/encriptado
Guarda a OpenAI API key utilizada para a geração.
O valor é encriptado pelo Magento usando:
Magento\Config\Model\Config\Backend\EncryptedImportante:
- não coloque a API key diretamente no código,
- não faça commit de chaves de ambiente,
- limite o acesso a este campo por ACL,
- use uma chave com permissões adequadas ao projeto.
OpenAI Model
Tipo: Select
Define o modelo OpenAI utilizado para a geração.
Exemplo:
gpt-4.1A lista é obtida dinamicamente da OpenAI Models API usando a API key configurada. O módulo filtra a resposta para identificadores de modelos GPT e coloca a lista em cache por um curto período para não chamar a API sempre que a configuração é aberta.
Se a API key ainda não tiver sido guardada, o campo mostrará uma opção de recurso e pedirá ao administrador para guardar a chave.
Se a OpenAI API estiver temporariamente indisponível, o campo mantém o modelo atualmente configurado, se possível.
Use um modelo que suporte o tipo de dados de entrada necessário:
- geração de texto para prompts e conteúdo do modelo,
- modelo com suporte para imagens, se forem usados projetos gráficos de referência.
O modelo selecionado influencia a qualidade do resultado, o tempo de resposta e o custo.
Request Timeout
Tipo: Number
Exemplo de valor predefinido:
120Tempo máximo em segundos permitido para o pedido à OpenAI API.
Valores recomendados:
60para geração curta de texto,120ou mais para geração HTML/CSS complexa,- valores superiores apenas quando a infraestrutura permite tarefas mais longas na fila.
O timeout aplica-se ao processamento em segundo plano, não ao pedido do formulário administrativo.
Maximum Retries
Tipo: Number
Exemplo de valor predefinido:
2Define quantas vezes o consumer pode repetir automaticamente uma tarefa de geração falhada.
As repetições são úteis para erros temporários, tais como:
- timeout da API,
- erro temporário do provider,
- rate limit,
- problema de rede.
Erros permanentes, por exemplo configuração incorreta ou resposta inválida da IA, devem ser verificados nos detalhes da tarefa.
Technical Prompt
Tipo: Textarea
Este prompt é aplicado a cada pedido de geração. Deve conter regras técnicas que têm sempre de ser preservadas.
Exemplo:
You are an assistant generating Magento 2 email templates.Return only JSON that matches the provided schema.Keep Magento directives valid.Do not invent Magento variables.Do not add JavaScript.Put CSS in template_styles unless inline styles are required for email compatibility.Preserve required variables and add warnings when a requested change is risky.When assets are provided, use only the URLs from the assets section, preserve alt text, apply target links to clickable images, use banners and icons according to their sort_order, and do not invent additional image URLs.Use este campo para instruções estáveis, tais como:
- preservar diretivas Magento,
- manter variáveis obrigatórias,
- evitar JavaScript,
- devolver apenas JSON,
- escrever HTML compatível com clientes de e-mail,
- usar CSS no campo correto do resultado.
Não use este campo para instruções criativas pontuais. Para isso serve o AI Prompt no formulário do modelo.
Default User Prompt
Tipo: Textarea
Este prompt é mostrado por predefinição na secção IA do editor de modelos de e-mail.
Exemplo:
Improve this Magento email template while keeping all required Magento variables and directives valid.O administrador pode alterá-lo antes de criar uma tarefa de geração.
Use este campo para definir uma instrução predefinida prática para tarefas típicas de geração.
Allowed Design File Types
Tipo: Text
Exemplo de valor predefinido:
png,jpg,jpeg,webp,html,htm,txtLista de extensões de ficheiro permitidas para o projeto de referência opcional, separadas por vírgulas.
Exemplos suportados:
pngjpgjpegwebphtmlhtmtxt
Em produção, use uma lista tão restritiva quanto possível. Não permita tipos de ficheiro que não sejam necessários no processo.
Maximum Design File Size
Tipo: Number
Exemplo de valor predefinido:
5242880Tamanho máximo do ficheiro de referência em bytes.
Exemplos:
1048576= 1 MB5242880= 5 MB10485760= 10 MB
Ficheiros grandes aumentam o tamanho do payload e podem atrasar a geração ou exceder os limites do provider.
Automatically Apply Result
Tipo: Yes/No
Predefinição: No
Define se um resultado de IA correto deve substituir imediatamente os campos nativos do modelo Magento.
Quando definido como Yes, o consumer guarda o resultado gerado em:
- Template Name
- Template Subject
- Template Content
- Template Styles
Quando definido como No, o resultado é guardado na tarefa e o administrador pode verificá-lo antes da aplicação manual.
Definição recomendada para produção:
NoA aceitação manual é mais segura, porque o resultado da IA pode estar tecnicamente correto, mas ainda exigir revisão de marca, legal ou de layout.
Keep Request and Response Payloads
Tipo: Yes/No
Predefinição: Yes
Define se o módulo guarda os payloads completos de pedido e resposta no registo da tarefa.
Quando a opção está ativada, os detalhes da tarefa podem mostrar:
- snapshot do modelo enviado para a IA,
- variáveis disponíveis,
- prompts,
- metadados do projeto de referência,
- resposta da IA.
Isto é útil para debug e auditoria.
Em ambientes de produção, verifique os requisitos de privacidade antes de ativar esta opção. O módulo não deve enviar dados reais de clientes para a IA, mas os payloads podem ainda conter conteúdo de modelos sensível do ponto de vista do negócio.
Retention Days
Tipo: Number
Exemplo de valor predefinido:
30Define durante quanto tempo as tarefas antigas devem ser armazenadas.
Este valor documenta a política de retenção pretendida. O projeto pode usá-lo para implementar limpeza cíclica de acordo com os requisitos operacionais.
7. Exemplo: gerar o modelo New Order Confirmation for Guest
Este exemplo descreve o processo completo para gerar um modelo de e-mail Magento melhorado para:
New Order Confirmation for GuestPasso 1: Configure o módulo
Aceda a:
Stores > Configuration > AI Email Generation > AI Email Theme GeneratorDefina:
Enabled = YesAPI Provider = OpenAIOpenAI API Key = OpenAI Model = gpt-4.1Request Timeout = 120Maximum Retries = 2Automatically Apply Result = NoKeep Request and Response Payloads = Yes Guarde a configuração e limpe a cache, se o Magento o solicitar.
Passo 2: Inicie o queue consumer
Execute:
bin/magento queue:consumers:start kowal.ai_email.generate.consumerDurante os testes, o processo deve estar sempre em execução.
Passo 3: Crie um modelo Magento nativo
Aceda a:
Marketing > Communications > Email TemplatesClique em:
Add New TemplateNo campo Template, escolha:
New Order Confirmation for GuestClique em:
Load TemplateO Magento preencherá os campos nativos:
- Template Subject
- Template Content
- Template Styles
Defina o nome do modelo, por exemplo:
New Order Confirmation for Guest - AI DraftGuarde o modelo.
O processo de geração por IA exige um modelo guardado, porque a tarefa deve ter um template_id persistente.
Passo 4: Preencha o AI Prompt
Depois de guardar, abra novamente o modelo, se necessário. O editor padrão de modelos de e-mail Magento inclui a secção AI Email Generation.
No campo AI Prompt, introduza a instrução de negócio, por exemplo:
Create a modern, clean transactional email for a premium fashion store.Keep all Magento order variables and directives valid.Improve the subject line and make the content easier to scan.Add a clear order summary section, shipping information section, and customer support footer.Use neutral colors, simple spacing, and email-client-safe HTML.Significado deste campo:
- descreve o efeito de negócio esperado,
- aplica-se apenas a uma tarefa de geração concreta,
- pode conter instruções sobre marca, tom de comunicação, layout ou conteúdo,
- não deve conter dados de API nem dados reais de clientes.
Passo 5: Opcionalmente, adicione Design Reference
Use Design Reference se o e-mail gerado deve seguir uma direção visual específica.
Ficheiros de exemplo:
order-email-reference.pngbrand-email-layout.webpemail-layout.htmldesign-notes.txt
Significado deste campo:
- dá à IA contexto visual ou estrutural adicional,
- ajuda a adaptar o modelo ao projeto gráfico,
- é opcional,
- tem de cumprir os limites de extensões e tamanho de ficheiro.
Se nenhum projeto de referência for adicionado, a IA usará apenas o conteúdo do modelo, variáveis, prompt técnico e prompt do utilizador.
Passo 6: Opcionalmente, adicione Error Screenshot
Use Error Screenshot se quiser mostrar à IA um problema atual de renderização, layout ou validação do modelo.
Exemplos:
- captura de ecrã de um cabeçalho mal alinhado,
- screenshot de um problema com banner,
- pré-visualização do e-mail com espaçamento incorreto,
- captura de um cliente de e-mail a mostrar um problema de responsividade,
- screenshot de uma mensagem de erro de uma ferramenta de teste.
Este campo é enviado para a IA como uma secção JSON separada:
{ 'error_screenshot': { 'type': 'image', 'filename': 'email-rendering-error.png', 'mime_type': 'image/png', 'content_base64': '...', 'purpose': 'current_error_context', 'description': 'Screenshot showing current rendering, layout, visual, or validation errors. Use it to understand what should be fixed. This is not a design reference.' }}Significado deste campo:
- mostra à IA o erro atual a corrigir,
- não é um projeto gráfico nem um modelo do aspeto pretendido,
- ajuda a IA a compreender o que não funciona atualmente,
- deve ser usado juntamente com uma descrição clara do problema no
AI Prompt.
Exemplo de prompt:
Use the attached error screenshot only to understand the current rendering issue.Fix the spacing problem visible in the screenshot while preserving Magento variables.Do not treat the screenshot as the target design.Passo 7: Adicione AI Assets estruturados
O editor inclui a área AI Assets. Estes recursos são guardados junto do modelo Magento e enviados para a IA como URLs de media frontend agrupados.
Grupos de recursos disponíveis:
| Campo | Significado |
|---|---|
| Logo | Logótipo da marca usado no cabeçalho ou rodapé da mensagem. |
| Header Image | Imagem principal para a parte superior da mensagem. |
| Banners | Lista dinâmica de banners promocionais ou informativos. |
| Icons | Lista dinâmica de pequenos elementos gráficos, por exemplo benefícios ou ícones de serviços. |
Cada recurso pode conter:
| Campo | Significado |
|---|---|
| File | Ficheiro gráfico enviado para o Magento media storage. |
| Label | Nome interno que ajuda a IA a compreender a finalidade do recurso. |
| Alt Text | Texto usado no atributo alt da imagem. |
| Target URL | Link usado quando a imagem deve ser clicável. |
| Sort Order | Prioridade de apresentação de banners e ícones. |
Para banners e ícones, clique em:
Add BannerAdd IconO módulo guarda os recursos enviados no Magento media storage e envia para a IA URLs frontend públicos na estrutura:
{ 'assets': { 'logo': { 'label': 'Brand logo', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/logo/logo.png', 'alt': 'Brand logo', 'link': 'https://example.com/', 'sort_order': 0 }, 'header_image': { 'label': 'Spring campaign header', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/header/header.jpg', 'alt': 'Spring collection', 'link': 'https://example.com/spring', 'sort_order': 0 }, 'banners': [ { 'label': 'Main promotion', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/banner/banner.jpg', 'alt': '20% off new collection', 'link': 'https://example.com/new', 'sort_order': 10 } ], 'icons': [ { 'label': 'Free delivery', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/icon/delivery.png', 'alt': 'Free delivery', 'link': 'https://example.com/delivery', 'sort_order': 10 } ] }}Nos prompts, refira estes grupos diretamente. Exemplo:
Use the uploaded logo as the main brand mark.Use the header image at the top of the email.Place banners below the order summary using their sort order.Use icons in a benefits row and link each icon to its target URL.Always preserve alt text.Passo 8: Selecione a geração após guardar
Ative:
Generate with AI after savingSignificado deste campo:
- o Magento guarda primeiro o modelo através da ação nativa save padrão,
- após uma gravação correta, o módulo cria uma tarefa de geração por IA,
- o projeto de referência enviado é anexado à tarefa,
- a tarefa é processada de forma assíncrona pelo queue consumer.
Se a checkbox não estiver selecionada, guardar o modelo funciona exatamente como a gravação padrão do Magento e nenhuma tarefa de IA será criada.
Passo 9: Guarde o modelo
Clique no botão padrão do Magento:
Save TemplateDepois de guardar o modelo, o módulo cria uma tarefa de geração.
Neste momento:
- a gravação nativa do modelo está concluída,
- o estado da tarefa começa em
pending, - o queue consumer processa a tarefa em segundo plano.
Passo 10: Verifique a tarefa
Aceda a:
Marketing > Communications > AI Email Generation JobsAbra a tarefa criada.
Campos mais importantes:
| Campo | Significado |
|---|---|
| Status | Estado atual do processamento. |
| Template ID | ID do modelo de e-mail Magento nativo. |
| Template Name | Nome do modelo guardado no momento de criação da tarefa. |
| Model | Modelo OpenAI usado para a geração. |
| Attempts | Número de tentativas de processamento. |
| Prompt | Prompt do utilizador enviado a partir do formulário do modelo. |
| Request Payload | JSON enviado para a IA, se a gravação de payloads estiver ativada. |
| Response Payload | JSON devolvido pela IA, se a gravação de payloads estiver ativada. |
| Generated Result | Resultado analisado e pronto a aplicar. |
| Assets | URLs frontend públicos e metadados de logótipo, cabeçalho, banners e ícones. |
| Error Screenshot | Screenshot com erros atuais, enviado para a IA como contexto de correção. |
| Warnings | Avisos da IA relativos a requisitos arriscados ou incompletos. |
| Error Message | Causa do erro quando a geração falha. |
| Status History | Histórico de alterações do estado da tarefa. |
Estados típicos:
| Estado | Significado |
|---|---|
pending | A tarefa foi criada e aguarda o consumer. |
processing | O consumer está atualmente a processar a tarefa. |
retry_scheduled | A tentativa anterior falhou e foi agendada uma repetição. |
completed | A IA devolveu um resultado correto. |
failed | A tarefa falhou após todas as tentativas ou a validação não foi bem-sucedida. |
cancelled | O administrador cancelou a tarefa. |
Passo 11: Aplique o resultado
Se Automatically Apply Result = No, o resultado não é guardado automaticamente no modelo Magento.
Verifique:
- Template Name
- Template Subject
- Template Content
- Template Styles
- Warnings
- Request Payload
- Response Payload
Se o resultado estiver correto, clique em:
Apply ResultO módulo guardará os valores gerados nos campos nativos do modelo Magento.
Passo 12: Valide o modelo de e-mail nativo
Volte a:
Marketing > Communications > Email TemplatesAbra o modelo e verifique se:
- Template Name foi atualizado,
- Template Subject foi atualizado,
- Template Content contém o HTML e as diretivas Magento esperados,
- Template Styles contém o CSS esperado,
- as variáveis Magento obrigatórias não foram removidas.
Envie uma mensagem de teste ou execute um fluxo de encomenda de teste de acordo com o processo QA padrão do projeto.
Passo 13: Envie uma nova correção para a IA
Depois de aplicar o resultado através de Apply Result, a versão atual do modelo fica guardada nos campos nativos do Magento. Isto significa que o pedido de IA seguinte será baseado nesta versão, e não no modelo original.
Pode aperfeiçoar o mesmo modelo várias vezes:
- Aplique o resultado da IA através de
Apply Result. - Abra novamente o modelo em
Marketing > Communications > Email Templates. - Introduza um novo prompt que descreva a correção concreta.
- Se o problema for visual, adicione
Error Screenshot. - Selecione
Generate with AI after saving. - Guarde o modelo.
- Verifique a nova tarefa e aplique o resultado, se estiver correto.
Nas correções seguintes, trate o AI Prompt como uma descrição da alteração à versão atual. O ideal é indicar:
- o que está atualmente incorreto,
- que efeito deve ser alcançado,
- que elementos a IA não deve alterar,
- se o
Error Screenshotanexado mostra um erro de renderização, layout visual, problema de responsividade ou mensagem de validação.
Exemplo de prompt para uma correção seguinte:
Use the current saved template as the base.Fix the spacing issue visible in the attached error screenshot.Keep the current header layout, all Magento variables, and the existing Template Styles structure.Do not redesign the whole email.Este workflow é útil quando a primeira versão está próxima do resultado esperado, mas exige refinamento de detalhes como espaçamentos, responsividade, visibilidade de banners, posição do logótipo ou estilo dos botões.
Pode repetir este ciclo várias vezes. Cada nova tarefa cria uma entrada separada no histórico, pelo que é possível voltar a prompts, payloads e respostas da IA anteriores para verificar que instrução levou a uma alteração específica.
8. Significado dos campos do payload de IA
O módulo envia para a IA um payload estruturado. As secções mais importantes são:
template
Contém o estado atual do modelo Magento:
- ID do modelo,
- nome do modelo,
- subject,
- content,
- styles,
- código original do modelo.
A IA usa esta secção como material base para a geração.
Importante: se anteriormente foi aplicado um resultado de IA através de Apply Result, a secção template já contém essa versão atualizada. Assim, a geração seguinte pode funcionar como uma correção ao modelo atual.
variables
Contém variáveis e diretivas Magento detetadas no modelo.
A IA deve preservar estes valores e não deve inventar variáveis não suportadas.
prompts
Contém:
technical- prompt técnico global da configuração,user- prompt introduzido no editor do modelo.
O prompt técnico protege a estrutura específica do Magento. O prompt do utilizador descreve o resultado esperado para um modelo.
design_reference
Contém metadados opcionais e o conteúdo do projeto de referência enviado.
A secção fica vazia quando nenhum ficheiro de referência é enviado.
error_screenshot
Contém um screenshot opcional que mostra erros atuais de renderização, layout, visuais ou de validação.
Esta secção tem uma descrição purpose e description para que a IA saiba que o ficheiro serve para compreender o problema, e não como modelo do projeto de destino.
A secção fica vazia quando não é enviado nenhum screenshot.
Nas correções seguintes, vale a pena usar error_screenshot juntamente com um prompt preciso que indique o que deve ser corrigido e o que não deve ser alterado. Assim, a IA pode corrigir um problema específico sem reconstruir todo o modelo.
Exemplo: depois de aplicar o primeiro resultado da IA, o administrador repara que no Gmail o banner se sobrepõe à secção de resumo da encomenda. No pedido seguinte, anexa um screenshot dessa visualização e introduz um prompt a pedir apenas a correção dos espaçamentos e da largura do banner. O payload continua a conter o Template Content e os Template Styles atuais, pelo que a IA trabalha sobre a última versão guardada.
assets
Contém recursos gráficos estruturados guardados para o modelo:
- logótipo,
- header image,
- banners,
- icons.
Cada recurso contém URL público de media, label, alt text, target URL, sort order e filename.
A IA deve usar estes URLs ao construir o HTML e não deve inventar endereços de imagens adicionais.
store_context
Contém informações básicas sobre a loja, tais como:
- store ID,
- locale,
- base URL.
A IA pode usá-las para compreender o idioma e o contexto, mas não deve receber dados reais de clientes ou encomendas.
9. Resolução de problemas
A tarefa permanece no estado pending
Causa mais provável:
- o queue consumer não está em execução.
Verifique:
bin/magento queue:consumers:start kowal.ai_email.generate.consumerA página de configuração mostra access denied
Verifique as permissões ACL para:
Kowal_AiEmailThemeGenerator::settingsDepois de alterar as permissões do administrador, termine a sessão e volte a iniciar sessão.
A geração termina com erro de falta de API key
Verifique:
OpenAI API KeyCertifique-se de que o módulo está ativado e que a configuração foi guardada no scope correto.
O resultado da IA tem o estado completed, mas o modelo não foi atualizado
Verifique:
Automatically Apply ResultSe a opção estiver definida como No, abra a tarefa e clique em:
Apply ResultA correção seguinte não considera o resultado anterior
Verifique se o resultado anterior foi aplicado através de:
Apply ResultA geração seguinte baseia-se no modelo Magento atualmente guardado. Se o resultado do job tiver estado completed, mas não tiver sido aplicado, o job seguinte continuará a basear-se na versão anterior do modelo.
A resposta da IA foi rejeitada
O módulo valida o JSON devolvido. Pode rejeitar o resultado se:
- faltarem campos obrigatórios,
- os campos obrigatórios tiverem tipos incorretos,
- o nome do modelo, subject ou content estiverem vazios,
- content contiver a tag
script, - o resultado não for JSON válido.
Verifique a mensagem de erro na tarefa e repita a geração com um prompt mais claro.
10. Definições recomendadas para produção
Valores iniciais recomendados:
Enabled = YesRequest Timeout = 120Maximum Retries = 2Automatically Apply Result = NoKeep Request and Response Payloads = Yes for testing, No or limited retention for productionRetention Days = 30Use a aplicação manual do resultado até a equipa ter confiança de que os prompts, o modelo escolhido e as regras de validação produzem modelos consistentes.