From 02b81beb7ab017fa2d37d3406eb707d7644989b4 Mon Sep 17 00:00:00 2001 From: Anderson Silva Date: Wed, 3 Sep 2025 16:08:15 -0300 Subject: [PATCH 1/4] 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 | 203 ++++++++++++++++++ evolution-bot-linkpreview-example.md | 147 +++++++++++++ send-text-api-documentation.md | 0 .../services/evolutionBot.service.ts | 29 ++- 4 files changed, 377 insertions(+), 2 deletions(-) create mode 100644 evolution-bot-documentation.md create mode 100644 evolution-bot-linkpreview-example.md create mode 100644 send-text-api-documentation.md diff --git a/evolution-bot-documentation.md b/evolution-bot-documentation.md new file mode 100644 index 00000000..2c65d8f9 --- /dev/null +++ b/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* diff --git a/evolution-bot-linkpreview-example.md b/evolution-bot-linkpreview-example.md new file mode 100644 index 00000000..9db76581 --- /dev/null +++ b/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 + "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.* diff --git a/send-text-api-documentation.md b/send-text-api-documentation.md new file mode 100644 index 00000000..e69de29b diff --git a/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts b/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts index 081c2ffc..f6bcf8f1 100644 --- a/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts +++ b/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts @@ -106,26 +106,51 @@ export class EvolutionBotService extends BaseChatbotService Date: Wed, 3 Sep 2025 19:59:24 -0300 Subject: [PATCH 2/4] chore: remove documentation .md files - Remove evolution-bot-documentation.md - Remove evolution-bot-linkpreview-example.md - Remove send-text-api-documentation.md - Keep only the core linkPreview implementation --- evolution-bot-documentation.md | 203 --------------------------- evolution-bot-linkpreview-example.md | 147 ------------------- send-text-api-documentation.md | 0 3 files changed, 350 deletions(-) delete mode 100644 evolution-bot-documentation.md delete mode 100644 evolution-bot-linkpreview-example.md delete mode 100644 send-text-api-documentation.md diff --git a/evolution-bot-documentation.md b/evolution-bot-documentation.md deleted file mode 100644 index 2c65d8f9..00000000 --- a/evolution-bot-documentation.md +++ /dev/null @@ -1,203 +0,0 @@ -# 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* diff --git a/evolution-bot-linkpreview-example.md b/evolution-bot-linkpreview-example.md deleted file mode 100644 index 9db76581..00000000 --- a/evolution-bot-linkpreview-example.md +++ /dev/null @@ -1,147 +0,0 @@ -# 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 - "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.* diff --git a/send-text-api-documentation.md b/send-text-api-documentation.md deleted file mode 100644 index e69de29b..00000000 From 1be58c8487ec669d0a1eec3168edad04469674ba Mon Sep 17 00:00:00 2001 From: Anderson Silva Date: Thu, 4 Sep 2025 12:19:51 -0300 Subject: [PATCH 3/4] refactor: improve linkPreview implementation based on PR feedback - Default linkPreview to true when not specified for backward compatibility - Validate linkPreview is boolean before passing to textMessage - Consolidate debug logs and remove sensitive data from logging - Sanitize API keys in debug output ([REDACTED]) - Reduce log verbosity while maintaining debugging capability - Ensure robust fallback behavior for malformed responses Addresses PR feedback regarding: - Backward compatibility preservation - Security considerations in logging - Input validation and error handling --- .../services/evolutionBot.service.ts | 34 ++++++++++++------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts b/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts index f6bcf8f1..2a2cbeea 100644 --- a/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts +++ b/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts @@ -106,49 +106,57 @@ export class EvolutionBotService extends BaseChatbotService Date: Thu, 4 Sep 2025 14:35:56 -0300 Subject: [PATCH 4/4] style: clean up code formatting for linkPreview implementation - Remove unnecessary trailing whitespace - Use shorthand property syntax for linkPreview parameter - Apply ESLint formatting standards - Maintain code consistency and readability --- .../chatbot/evolutionBot/services/evolutionBot.service.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts b/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts index 2a2cbeea..b82e8fe1 100644 --- a/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts +++ b/src/api/integrations/chatbot/evolutionBot/services/evolutionBot.service.ts @@ -130,7 +130,7 @@ export class EvolutionBotService extends BaseChatbotService