feat: implement linkPreview support for Evolution Bot

- Add linkPreview extraction from webhook/n8n response
- Implement linkPreview parameter in textMessage calls
- Add debug logging for linkPreview functionality
- Support for disabling link previews when linkPreview: false
- Add comprehensive documentation for linkPreview feature

Usage:
- Return { "message": "text", "linkPreview": false } from webhook to disable preview
- Return { "message": "text", "linkPreview": true } from webhook to enable preview
- Omit linkPreview for default WhatsApp behavior

evolution-bot-documentation.md

@@ -0,0 +1,203 @@
+# Evolution Bot
+
+O Evolution Bot é uma integração de chatbot universal que permite a utilização de qualquer URL de API ou automação para criar interações automatizadas. Ao utilizar o Evolution Bot, sua API deve retornar a resposta na forma de um JSON contendo o campo `message`, que será enviado de volta ao usuário. Este sistema oferece flexibilidade para construir chatbots que se integram perfeitamente com suas APIs personalizadas.
+
+## 1. Criação de Bots no Evolution Bot
+
+Você pode configurar bots no Evolution Bot utilizando triggers para iniciar as interações. A configuração do bot pode ser feita através do endpoint `/evolutionBot/create/{{instance}}`.
+
+### Endpoint para Criação de Bots
+
+#### Endpoint
+
+```
+POST {{baseUrl}}/evolutionBot/create/{{instance}}
+```
+
+#### Corpo da Requisição
+
+Aqui está um exemplo de corpo JSON para configurar um bot no Evolution Bot:
+
+```json
+{
+    "enabled": true,
+    "apiUrl": "http://api.site.com/v1",
+    "apiKey": "app-123456", // optional
+    // opções
+    "triggerType": "keyword", /* all ou keyword */
+    "triggerOperator": "equals", /* contains, equals, startsWith, endsWith, regex, none */
+    "triggerValue": "teste",
+    "expire": 0,
+    "keywordFinish": "#SAIR",
+    "delayMessage": 1000,
+    "unknownMessage": "Mensagem não reconhecida",
+    "listeningFromMe": false,
+    "stopBotFromMe": false,
+    "keepOpen": false,
+    "debounceTime": 0,
+    "ignoreJids": []
+}
+```
+
+### Explicação dos Parâmetros
+
+- `enabled`: Ativa (`true`) ou desativa (`false`) o bot.
+- `apiUrl`: URL da API que será chamada pelo bot (sem a `/` no final).
+- `apiKey`: Chave da API fornecida pela sua aplicação (opcional).
+
+**Opções:**
+- `triggerType`: Tipo de trigger para iniciar o bot (`all` ou `keyword`).
+- `triggerOperator`: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`).
+- `triggerValue`: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex).
+- `expire`: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou.
+- `keywordFinish`: Palavra-chave que encerra a sessão do bot.
+- `delayMessage`: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem.
+- `unknownMessage`: Mensagem enviada quando a entrada do usuário não é reconhecida.
+- `listeningFromMe`: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`).
+- `stopBotFromMe`: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`).
+- `keepOpen`: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato.
+- `debounceTime`: Tempo (em segundos) para juntar várias mensagens em uma só.
+- `ignoreJids`: Lista de JIDs de contatos que não ativarão o bot.
+
+### Exemplo de Retorno da API
+
+A resposta da sua API deve estar no formato JSON e conter a mensagem a ser enviada ao usuário no campo `message`:
+
+```json
+{
+    "message": "Sua resposta aqui",
+    "linkPreview": false
+}
+```
+
+#### Opções Avançadas de Resposta
+
+Sua API pode retornar campos adicionais para controlar como a mensagem é enviada:
+
+- **`message`** (string, obrigatório): O texto da mensagem a ser enviada
+- **`linkPreview`** (boolean, opcional): 
+  - `true`: Habilita preview de links na mensagem (padrão)
+  - `false`: Desabilita preview de links ⚠️ **Recomendado quando a mensagem contém emails ou URLs**
+
+#### Exemplo com linkPreview desabilitado:
+
+```json
+{
+    "message": "Seu email de confirmação: user@example.com\n\nAcesse: https://site.com/confirmar",
+    "linkPreview": false
+}
+```
+
+**💡 Dica:** Use `linkPreview: false` quando:
+- A mensagem contém emails
+- Há múltiplas URLs
+- O preview tornaria a mensagem confusa
+
+## 2. Configurações Padrão do Evolution Bot
+
+Você pode definir configurações padrão que serão aplicadas caso os parâmetros não sejam passados durante a criação do bot.
+
+### Endpoint para Configurações Padrão
+
+#### Endpoint
+
+```
+POST {{baseUrl}}/evolutionBot/settings/{{instance}}
+```
+
+#### Corpo da Requisição
+
+Aqui está um exemplo de configuração padrão:
+
+```json
+{
+    "expire": 20,
+    "keywordFinish": "#SAIR",
+    "delayMessage": 1000,
+    "unknownMessage": "Mensagem não reconhecida",
+    "listeningFromMe": false,
+    "stopBotFromMe": false,
+    "keepOpen": false,
+    "debounceTime": 0,
+    "ignoreJids": [],
+    "evolutionBotIdFallback": "clyja4oys0a3uqpy7k3bd7swe"
+}
+```
+
+### Explicação dos Parâmetros
+
+- `expire`: Tempo em minutos após o qual o bot expira.
+- `keywordFinish`: Palavra-chave que encerra a sessão do bot.
+- `delayMessage`: Delay para simular a digitação antes de enviar uma mensagem.
+- `unknownMessage`: Mensagem enviada quando a entrada do usuário não é reconhecida.
+- `listeningFromMe`: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário.
+- `stopBotFromMe`: Define se o bot deve parar quando o próprio usuário envia uma mensagem.
+- `keepOpen`: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato.
+- `debounceTime`: Tempo para juntar várias mensagens em uma só.
+- `ignoreJids`: Lista de JIDs de contatos que não ativarão o bot.
+- `evolutionBotIdFallback`: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado.
+
+## 3. Gerenciamento de Sessões do Evolution Bot
+
+Você pode gerenciar as sessões do bot, alterando o status entre aberta, pausada ou fechada para cada contato específico.
+
+### Endpoint para Gerenciamento de Sessões
+
+#### Endpoint
+
+```
+POST {{baseUrl}}/evolutionBot/changeStatus/{{instance}}
+```
+
+#### Corpo da Requisição
+
+Aqui está um exemplo de como gerenciar o status da sessão:
+
+```json
+{
+    "remoteJid": "5511912345678@s.whatsapp.net",
+    "status": "closed"
+}
+```
+
+### Explicação dos Parâmetros
+
+- `remoteJid`: JID (identificador) do contato no WhatsApp.
+- `status`: Status da sessão (`opened`, `paused`, `closed`).
+
+## 4. Variáveis Automáticas e Especiais no Evolution Bot
+
+Quando uma sessão do Evolution Bot é iniciada, algumas variáveis predefinidas são automaticamente enviadas:
+
+```javascript
+inputs: {
+    remoteJid: "JID do contato",
+    pushName: "Nome do contato",
+    instanceName: "Nome da instância",
+    serverUrl: "URL do servidor da API",
+    apiKey: "Chave de API da Evolution"
+};
+```
+
+### Explicação das Variáveis Automáticas
+
+- `remoteJid`: JID do contato com quem o bot está interagindo.
+- `pushName`: Nome do contato no WhatsApp.
+- `instanceName`: Nome da instância que está executando o bot.
+- `serverUrl`: URL do servidor onde a Evolution API está hospedada.
+- `apiKey`: Chave de API usada para autenticar as requisições.
+
+### Considerações Finais
+
+O Evolution Bot oferece uma plataforma flexível para integração de chatbots com suas APIs personalizadas, permitindo automação avançada e interações personalizadas no WhatsApp. Com o suporte para triggers, gerenciamento de sessões e configuração de variáveis automáticas, você pode construir uma experiência de chatbot robusta e eficaz para seus usuários.
+
+## Links Relacionados
+
+- [Chatwoot](https://doc.evolution-api.com/v2/pt/integrations/chatwoot)
+- [Typebot](https://doc.evolution-api.com/v2/pt/integrations/typebot)
+- [Website](https://evolution-api.com/)
+- [GitHub](https://github.com/EvolutionAPI/evolution-api)
+
+---
+
+*Documentação extraída de: https://doc.evolution-api.com/v2/pt/integrations/evolution-bot*

evolution-bot-linkpreview-example.md

@@ -0,0 +1,147 @@
+# Evolution Bot - Exemplo Prático com LinkPreview
+
+Este exemplo mostra como implementar uma API simples que utiliza o Evolution Bot com controle de link preview.
+
+## 1. Exemplo de API em Node.js/Express
+
+```javascript
+const express = require('express');
+const app = express();
+app.use(express.json());
+
+app.post('/webhook/evolutionbot', (req, res) => {
+  const { query, inputs } = req.body;
+  const userMessage = query.toLowerCase();
+  
+  // Exemplo 1: Mensagem com email (sem preview)
+  if (userMessage.includes('email')) {
+    return res.json({
+      message: `Seu email de confirmação foi enviado para: ${inputs.pushName}@exemplo.com\n\nVerifique sua caixa de entrada.`,
+      linkPreview: false  // ❌ Desabilita preview para evitar poluição visual
+    });
+  }
+  
+  // Exemplo 2: Mensagem com link promocional (com preview)  
+  if (userMessage.includes('promoção')) {
+    return res.json({
+      message: `🎉 Promoção especial disponível!\n\nAcesse: https://loja.exemplo.com/promocao`,
+      linkPreview: true   // ✅ Habilita preview para mostrar a página
+    });
+  }
+  
+  // Exemplo 3: Mensagem com múltiplos links (sem preview)
+  if (userMessage.includes('links')) {
+    return res.json({
+      message: `📋 Links importantes:\n\n• Site: https://site.com\n• Suporte: https://help.site.com\n• Contato: contato@site.com`,
+      linkPreview: false  // ❌ Múltiplos links ficariam confusos com preview
+    });
+  }
+  
+  // Exemplo 4: Resposta padrão
+  return res.json({
+    message: "Olá! Como posso ajudar você hoje?"
+    // linkPreview não especificado = true (padrão)
+  });
+});
+
+app.listen(3000, () => {
+  console.log('API do Evolution Bot rodando na porta 3000');
+});
+```
+
+## 2. Configuração do Evolution Bot
+
+```json
+{
+    "enabled": true,
+    "apiUrl": "http://sua-api.com/webhook/evolutionbot",
+    "apiKey": "sua-chave-opcional",
+    "triggerType": "all",
+    "delayMessage": 1000,
+    "unknownMessage": "Desculpe, não entendi. Digite 'ajuda' para ver as opções."
+}
+```
+
+## 3. Exemplos de Uso
+
+### ❌ Problema: Mensagem com preview desnecessário
+```json
+{
+    "message": "Confirme seu pedido acessando: https://loja.com/pedido/123 ou entre em contato: vendas@loja.com"
+    // Sem linkPreview = true (padrão) - Vai mostrar preview da URL e do email
+}
+```
+
+**Resultado:** Mensagem poluída visualmente no WhatsApp.
+
+### ✅ Solução: Desabilitar preview quando necessário
+```json
+{
+    "message": "Confirme seu pedido acessando: https://loja.com/pedido/123 ou entre em contato: vendas@loja.com",
+    "linkPreview": false
+}
+```
+
+**Resultado:** Mensagem limpa e fácil de ler.
+
+## 4. Casos de Uso Recomendados
+
+### Use `linkPreview: false` quando:
+- ✉️ Mensagem contém emails
+- 🔗 Múltiplas URLs na mesma mensagem
+- 📝 URLs são apenas referências/instruções
+- 🏷️ Mensagens curtas onde o preview é maior que o texto
+
+### Use `linkPreview: true` (ou omita) quando:
+- 📰 Compartilhamento de artigos/notícias
+- 🛒 Links promocionais/produtos
+- 🌐 Preview ajuda a dar contexto
+- 📱 Único link principal na mensagem
+
+## 5. Exemplo de Implementação em PHP
+
+```php
+<?php
+header('Content-Type: application/json');
+
+$input = json_decode(file_get_contents('php://input'), true);
+$query = strtolower($input['query'] ?? '');
+$inputs = $input['inputs'] ?? [];
+
+if (strpos($query, 'email') !== false) {
+    echo json_encode([
+        'message' => "Seu email de confirmação: " . $inputs['pushName'] . "@exemplo.com",
+        'linkPreview' => false
+    ]);
+} elseif (strpos($query, 'site') !== false) {
+    echo json_encode([
+        'message' => "Visite nosso site: https://exemplo.com",
+        'linkPreview' => true
+    ]);
+} else {
+    echo json_encode([
+        'message' => "Como posso ajudar?"
+    ]);
+}
+?>
+```
+
+## 6. Teste da Implementação
+
+Para testar sua implementação:
+
+1. Configure o Evolution Bot com sua `apiUrl`
+2. Envie mensagens de teste via WhatsApp
+3. Verifique se os previews aparecem/desaparecem conforme esperado
+4. Ajuste a lógica da sua API conforme necessário
+
+## 7. Dicas Importantes
+
+- 🔧 **Sempre teste** as mensagens no WhatsApp real para ver o resultado visual
+- ⚡ **Performance**: `linkPreview: false` pode carregar mensagens mais rápido
+- 📊 **Analytics**: Monitore quais tipos de mensagem têm melhor engajamento
+- 🎯 **UX**: Priorize a legibilidade da mensagem sobre a funcionalidade de preview
+
+---
+
+*Este exemplo mostra como implementar o controle de link preview no Evolution Bot de forma prática e eficiente.*

src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts

@@ -106,26 +106,51 @@ export class EvolutionBotService extends BaseChatbotService<EvolutionBot, Evolut
         };
       }
 
+      this.logger.debug(`[EvolutionBot] Sending request to endpoint: ${endpoint}`);
+      this.logger.debug(`[EvolutionBot] Payload being sent: ${JSON.stringify(payload, null, 2)}`);
+      this.logger.debug(`[EvolutionBot] Headers being sent: ${JSON.stringify(headers, null, 2)}`);
+
       const response = await axios.post(endpoint, payload, {
         headers,
       });
 
+      this.logger.debug(`[EvolutionBot] Received response status: ${response.status}`);
+      this.logger.debug(`[EvolutionBot] Received response data: ${JSON.stringify(response.data, null, 2)}`);
+
       if (instance.integration === Integration.WHATSAPP_BAILEYS) {
         await instance.client.sendPresenceUpdate('paused', remoteJid);
       }
 
       let message = response?.data?.message;
+      const linkPreview = response?.data?.linkPreview; // Extract linkPreview from n8n response
+
+      this.logger.debug(`[EvolutionBot] Raw message from response: ${JSON.stringify(message)}`);
+      this.logger.debug(`[EvolutionBot] LinkPreview setting from response: ${linkPreview}`);
 
       if (message && typeof message === 'string' && message.startsWith("'") && message.endsWith("'")) {
         const innerContent = message.slice(1, -1);
         if (!innerContent.includes("'")) {
           message = innerContent;
+          this.logger.debug(`[EvolutionBot] Message cleaned (removed quotes): ${message}`);
         }
       }
 
       if (message) {
-        // Use the base class method to send the message to WhatsApp
+        this.logger.debug(`[EvolutionBot] Sending message to WhatsApp: ${message}`);
-        await this.sendMessageWhatsApp(instance, remoteJid, message, settings);
+        this.logger.debug(`[EvolutionBot] Using linkPreview: ${linkPreview}`);
+        // Send message directly with linkPreview option
+        await instance.textMessage(
+          {
+            number: remoteJid.split('@')[0],
+            delay: settings?.delayMessage || 1000,
+            text: message,
+            linkPreview: linkPreview, // Use linkPreview from n8n response
+          },
+          false,
+        );
+        this.logger.debug(`[EvolutionBot] Message sent successfully to WhatsApp`);
+      } else {
+        this.logger.warn(`[EvolutionBot] No message content received from bot response`);
       }
 
       // Send telemetry