From ceddace91513e22e252b6ef4cc002e953f5aeb86 Mon Sep 17 00:00:00 2001 From: Anderson Silva Date: Wed, 3 Sep 2025 19:59:24 -0300 Subject: [PATCH] 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