Assistente de IA para Salesforce que integra com n8n para fornecer respostas automáticas sobre processos operacionais, para auxiliar usuários Salesforce durante as tarefas diárias. Esse assistente é utilizado através de um componente Lightning Web Component (LWC).

• Sobre o Projeto
• Arquitetura do Componente
• Pré-requisitos
• Como Clonar e Configurar
• Configuração da Org Salesforce
• Como Utilizar o Componente
• Estrutura do Projeto
• Desenvolvimento

O PlaybookAIssistant é uma solução Salesforce que permite aos usuários fazer perguntas sobre processos de atendimento ao cliente e receber respostas automatizadas através de integração com workflows n8n, que realiza a consulta em uma base de conhecimento plugada ao n8n, como forma de automatizar a geração de respostas e facilitar as consultas de dúvidas operacionais. O componente apresenta uma interface amigável de chat diretamente nas páginas do Salesforce, o que garante que o usuário não precise alternar entre novas abas ou sistemas, garantindo eficiência e agilidade no dia a dia.

• Interface de chat intuitiva em Lightning Web Component
• Integração com n8n para processamento de IA
• Suporte a Rich Text nas respostas
• Gerenciamento de credenciais via Custom Metadata Type
• Tratamento robusto de erros e logging
• Disponível em Record Pages, App Pages e Home Pages

Localização: force-app/main/default/classes/N8nHttpClient.cls

Esta classe é responsável pela comunicação HTTP com o servidor n8n.

@AuraEnabled public static String sendRequest(String prompt)

• Entrada: Recebe a pergunta do usuário (prompt)
• Processo:
  1. Recupera credenciais do n8n do Custom Metadata Type N8nCredential__mdt
  2. Constrói requisição HTTP POST com o prompt no corpo
  3. Envia a requisição para o endpoint n8n configurado
  4. Valida a resposta HTTP (espera status 200)
  5. Retorna o corpo da resposta em formato JSON
• Saída: String JSON com a resposta do n8n

A classe espera um Custom Metadata Type chamado N8nCredential__mdt com um registro nomeado AuthRequest contendo:

• Url__c: URL base do servidor n8n
• Path__c: Caminho do endpoint/webhook
• Timeout__c (opcional): Timeout em milissegundos (padrão: 120000ms)

Localização: force-app/main/default/lwc/playbookAIssistantTool/

Este componente fornece a interface de usuário para interação com o assistente de IA.

playbookAIssistantTool/ ├── playbookAIssistantTool.js # Lógica do componente ├── playbookAIssistantTool.html # Template/UI ├── playbookAIssistantTool.css # Estilos customizados ├── playbookAIssistantTool.js-meta.xml # Configuração de exposição └── __tests__/ └── playbookAIssistantTool.test.js # Testes unitários 

1. Entrada do Usuário: handlePromptChange(event)

   • Captura o texto digitado no campo de input
   • Atualiza a propriedade prompt

2. Envio da Pergunta: handleClick()

   • Valida se o prompt não está vazio
   • Ativa o estado de loading (isLoading = true)
   • Chama método Apex N8nHttpClient.sendRequest(prompt)
   • Processa a resposta através de parseResponse()
   • Exibe toast de sucesso
   • Desativa loading e limpa o campo de input

3. Processamento da Resposta: parseResponse(result)

   • Tenta fazer parse do JSON retornado
   • Espera formato de array: [{"agentAnswer": "resposta aqui"}]
   • Extrai o campo agentAnswer do primeiro elemento
   • Fallback para resultado bruto se parsing falhar

4. Tratamento de Erros: handleError(error)

   • Loga erro no console
   • Extrai mensagem de erro do objeto Apex exception
   • Exibe toast de erro
   • Mostra mensagem de erro na interface

• lightning-card: Container principal com título
• lightning-input: Campo de texto para entrada do prompt
• lightning-button: Botão "Enviar"
• lightning-spinner: Indicador de carregamento
• lightning-formatted-rich-text: Exibição da resposta com suporte a rich text

.custom-chat-message_outbound { border-radius: 10px; background-color: #0070d2; /* Azul Salesforce */ color: white; align-self: flex-end; }

Antes de começar, certifique-se de ter instalado:

1. Node.js (versão 18 ou superior)

   • Download: https://nodejs.org/

2. Salesforce CLI (sf ou sfdx)

   npm install -g @salesforce/cli

3. Git

   • Download: https://git-scm.com/

4. Visual Studio Code (recomendado)

   • Download: https://code.visualstudio.com/
   • Extensão: Salesforce Extension Pack

5. Acesso a uma Org Salesforce

   • Developer Edition, Sandbox ou Scratch Org

6. Servidor n8n configurado (para integração funcionar)

   • URL e webhook endpoint configurados

# Clone o repositório git clone <URL_DO_REPOSITORIO> # Entre no diretório do projeto cd PlaybookAIssistant

# Instalar dependências NPM para desenvolvimento npm install

Você pode usar uma Scratch Org ou uma Sandbox/Developer Org:

# Criar scratch org com duração de 7 dias sf org create scratch -f config/project-scratch-def.json -a PlaybookAssistant -d 7 # Definir como org padrão sf config set target-org PlaybookAssistant

# Autenticar com uma org existente sf org login web -a MyOrgAlias # Definir como org padrão sf config set target-org MyOrgAlias

# Deploy de todo o código fonte sf project deploy start -d force-app/main/default # OU usando manifest (package.xml) sf project deploy start -x manifest/package.xml

# Verificar status do deploy sf project deploy report # Abrir a org sf org open

Navegue para Setup → Custom Metadata Types → New Custom Metadata Type

Configurações:

• Label: N8n Credential
• Plural Label: N8n Credentials
• Object Name: N8nCredential
• API Name: N8nCredential__mdt

Campos Customizados:

Navegue para Setup → Custom Metadata Types → N8n Credentials → Manage Records → New

Valores:

• Label: AuthRequest
• N8n Credential Name: AuthRequest
• URL: https://seu-servidor-n8n.com (URL base do n8n)
• Path: /webhook/seu-endpoint (caminho do webhook)
• Timeout: 120000 (opcional, padrão 120 segundos)

Navegue para Setup → Remote Site Settings → New Remote Site

Configurações:

• Remote Site Name: n8n_server
• Remote Site URL: https://seu-servidor-n8n.com
• Active: ✓ (marcado)
• Description: Permite comunicação com servidor n8n

1. Navegue para qualquer página Lightning (Home, App ou Record Page)
2. Clique no ícone de engrenagem → Edit Page
3. No Lightning App Builder, localize o componente playbookAIssistantTool no painel de componentes
4. Arraste o componente para a área desejada da página
5. Clique em Save
6. Clique em Activate (se necessário) e defina como padrão da organização/app/perfil

1. Na página Lightning, localize o card "Dúvidas no processo? Pergunte ao PA!"
2. Digite sua pergunta no campo Prompt
3. Clique no botão Enviar
4. Aguarde o processamento (spinner de loading aparecerá)
5. A resposta será exibida na seção Resposta do PA:

Pergunta:

Como devo proceder quando um cliente solicita reembolso? 

Resposta esperada:

Para processar um reembolso, siga estes passos: 1. Verifique a política de reembolso aplicável 2. Valide o prazo de solicitação 3. Confirme o método de pagamento original 4. Preencha o formulário de autorização... 

PlaybookAIssistant/ │ ├── force-app/main/default/ # Código fonte principal │ ├── classes/ # Classes Apex │ │ ├── N8nHttpClient.cls # Cliente HTTP para n8n │ │ └── N8nHttpClient.cls-meta.xml │ │ │ └── lwc/ # Lightning Web Components │ └── playbookAIssistantTool/ # Componente principal │ ├── playbookAIssistantTool.js │ ├── playbookAIssistantTool.html │ ├── playbookAIssistantTool.css │ ├── playbookAIssistantTool.js-meta.xml │ └── __tests__/ │ └── playbookAIssistantTool.test.js │ ├── manifest/ │ └── package.xml # Manifest de deploy │ ├── config/ │ └── project-scratch-def.json # Definição de scratch org │ ├── scripts/ # Scripts auxiliares │ ├── apex/hello.apex # Exemplo Apex │ └── soql/account.soql # Exemplo SOQL │ ├── sfdx-project.json # Configuração SFDX ├── package.json # Dependências NPM ├── jest.config.js # Configuração de testes ├── eslint.config.js # Linting ├── .prettierrc # Formatação de código └── README.md # Este arquivo 

# Executar todos os testes npm test # Executar testes em modo watch npm run test:unit:watch # Gerar relatório de cobertura npm run test:unit:coverage

# Verificar problemas de linting npm run lint # Verificar formatação npm run prettier:verify # Formatar automaticamente todos os arquivos npm run prettier

# Deploy de um componente específico sf project deploy start -m LightningComponentBundle:playbookAIssistantTool # Deploy de uma classe específica sf project deploy start -m ApexClass:N8nHttpClient

# Ver logs da org sf apex tail log # Ver logs de debug específicos sf apex get log --log-id <LOG_ID>

Para que a integração funcione completamente, você precisa configurar um workflow n8n que:

1. Receba requisições POST no endpoint configurado
2. Processe o campo agentAnswer do body JSON
3. Execute a lógica de IA/processamento (GPT, Claude, ou outra IA)
4. Retorne array JSON no formato:

   [ { "agentAnswer": "Sua resposta aqui com suporte a rich text" } ]

Solução: Verifique se você adicionou o Remote Site Settings corretamente em Setup.

Solução: Certifique-se de que o registro AuthRequest existe no Custom Metadata Type N8nCredential__mdt.

Solução: Verifique se o componente está com isExposed=true no arquivo js-meta.xml e se o deploy foi bem-sucedido.

Solução: Aumente o valor do campo Timeout__c no Custom Metadata (valor em milissegundos).

• API Salesforce: 64.0 (Summer '24)
• Node.js: ≥ 18.x
• Salesforce CLI: Latest

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para mais detalhes.

A MIT License permite que você:

• ✅ Use comercialmente
• ✅ Modifique o código
• ✅ Distribua
• ✅ Use privativamente

A única exigência é manter o aviso de copyright e a licença em todas as cópias.

• Adicionar histórico de conversas
• Permitir exportar a conversa
• Implementar testes unitários completos
• Suporte a anexos/imagens
• Tradução para outros idiomas