Skip to content

Commit 02b81be

Browse files
dersonbsb2022dersonbsb2022
committed
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
1 parent c2085b5 commit 02b81be

File tree

4 files changed

+377
-2
lines changed

4 files changed

+377
-2
lines changed

‎evolution-bot-documentation.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Evolution Bot
2+
3+
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.
4+
5+
## 1. Criação de Bots no Evolution Bot
6+
7+
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}}`.
8+
9+
### Endpoint para Criação de Bots
10+
11+
#### Endpoint
12+
13+
```
14+
POST {{baseUrl}}/evolutionBot/create/{{instance}}
15+
```
16+
17+
#### Corpo da Requisição
18+
19+
Aqui está um exemplo de corpo JSON para configurar um bot no Evolution Bot:
20+
21+
```json
22+
{
23+
"enabled": true,
24+
"apiUrl": "http://api.site.com/v1",
25+
"apiKey": "app-123456", // optional
26+
// opções
27+
"triggerType": "keyword", /* all ou keyword */
28+
"triggerOperator": "equals", /* contains, equals, startsWith, endsWith, regex, none */
29+
"triggerValue": "teste",
30+
"expire": 0,
31+
"keywordFinish": "#SAIR",
32+
"delayMessage": 1000,
33+
"unknownMessage": "Mensagem não reconhecida",
34+
"listeningFromMe": false,
35+
"stopBotFromMe": false,
36+
"keepOpen": false,
37+
"debounceTime": 0,
38+
"ignoreJids": []
39+
}
40+
```
41+
42+
### Explicação dos Parâmetros
43+
44+
- `enabled`: Ativa (`true`) ou desativa (`false`) o bot.
45+
- `apiUrl`: URL da API que será chamada pelo bot (sem a `/` no final).
46+
- `apiKey`: Chave da API fornecida pela sua aplicação (opcional).
47+
48+
**Opções:**
49+
- `triggerType`: Tipo de trigger para iniciar o bot (`all` ou `keyword`).
50+
- `triggerOperator`: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`).
51+
- `triggerValue`: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex).
52+
- `expire`: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou.
53+
- `keywordFinish`: Palavra-chave que encerra a sessão do bot.
54+
- `delayMessage`: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem.
55+
- `unknownMessage`: Mensagem enviada quando a entrada do usuário não é reconhecida.
56+
- `listeningFromMe`: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`).
57+
- `stopBotFromMe`: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`).
58+
- `keepOpen`: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato.
59+
- `debounceTime`: Tempo (em segundos) para juntar várias mensagens em uma só.
60+
- `ignoreJids`: Lista de JIDs de contatos que não ativarão o bot.
61+
62+
### Exemplo de Retorno da API
63+
64+
A resposta da sua API deve estar no formato JSON e conter a mensagem a ser enviada ao usuário no campo `message`:
65+
66+
```json
67+
{
68+
"message": "Sua resposta aqui",
69+
"linkPreview": false
70+
}
71+
```
72+
73+
#### Opções Avançadas de Resposta
74+
75+
Sua API pode retornar campos adicionais para controlar como a mensagem é enviada:
76+
77+
- **`message`** (string, obrigatório): O texto da mensagem a ser enviada
78+
- **`linkPreview`** (boolean, opcional):
79+
- `true`: Habilita preview de links na mensagem (padrão)
80+
- `false`: Desabilita preview de links ⚠️ **Recomendado quando a mensagem contém emails ou URLs**
81+
82+
#### Exemplo com linkPreview desabilitado:
83+
84+
```json
85+
{
86+
"message": "Seu email de confirmação: user@example.com\n\nAcesse: https://site.com/confirmar",
87+
"linkPreview": false
88+
}
89+
```
90+
91+
**💡 Dica:** Use `linkPreview: false` quando:
92+
- A mensagem contém emails
93+
- Há múltiplas URLs
94+
- O preview tornaria a mensagem confusa
95+
96+
## 2. Configurações Padrão do Evolution Bot
97+
98+
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.
99+
100+
### Endpoint para Configurações Padrão
101+
102+
#### Endpoint
103+
104+
```
105+
POST {{baseUrl}}/evolutionBot/settings/{{instance}}
106+
```
107+
108+
#### Corpo da Requisição
109+
110+
Aqui está um exemplo de configuração padrão:
111+
112+
```json
113+
{
114+
"expire": 20,
115+
"keywordFinish": "#SAIR",
116+
"delayMessage": 1000,
117+
"unknownMessage": "Mensagem não reconhecida",
118+
"listeningFromMe": false,
119+
"stopBotFromMe": false,
120+
"keepOpen": false,
121+
"debounceTime": 0,
122+
"ignoreJids": [],
123+
"evolutionBotIdFallback": "clyja4oys0a3uqpy7k3bd7swe"
124+
}
125+
```
126+
127+
### Explicação dos Parâmetros
128+
129+
- `expire`: Tempo em minutos após o qual o bot expira.
130+
- `keywordFinish`: Palavra-chave que encerra a sessão do bot.
131+
- `delayMessage`: Delay para simular a digitação antes de enviar uma mensagem.
132+
- `unknownMessage`: Mensagem enviada quando a entrada do usuário não é reconhecida.
133+
- `listeningFromMe`: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário.
134+
- `stopBotFromMe`: Define se o bot deve parar quando o próprio usuário envia uma mensagem.
135+
- `keepOpen`: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato.
136+
- `debounceTime`: Tempo para juntar várias mensagens em uma só.
137+
- `ignoreJids`: Lista de JIDs de contatos que não ativarão o bot.
138+
- `evolutionBotIdFallback`: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado.
139+
140+
## 3. Gerenciamento de Sessões do Evolution Bot
141+
142+
Você pode gerenciar as sessões do bot, alterando o status entre aberta, pausada ou fechada para cada contato específico.
143+
144+
### Endpoint para Gerenciamento de Sessões
145+
146+
#### Endpoint
147+
148+
```
149+
POST {{baseUrl}}/evolutionBot/changeStatus/{{instance}}
150+
```
151+
152+
#### Corpo da Requisição
153+
154+
Aqui está um exemplo de como gerenciar o status da sessão:
155+
156+
```json
157+
{
158+
"remoteJid": "5511912345678@s.whatsapp.net",
159+
"status": "closed"
160+
}
161+
```
162+
163+
### Explicação dos Parâmetros
164+
165+
- `remoteJid`: JID (identificador) do contato no WhatsApp.
166+
- `status`: Status da sessão (`opened`, `paused`, `closed`).
167+
168+
## 4. Variáveis Automáticas e Especiais no Evolution Bot
169+
170+
Quando uma sessão do Evolution Bot é iniciada, algumas variáveis predefinidas são automaticamente enviadas:
171+
172+
```javascript
173+
inputs: {
174+
remoteJid: "JID do contato",
175+
pushName: "Nome do contato",
176+
instanceName: "Nome da instância",
177+
serverUrl: "URL do servidor da API",
178+
apiKey: "Chave de API da Evolution"
179+
};
180+
```
181+
182+
### Explicação das Variáveis Automáticas
183+
184+
- `remoteJid`: JID do contato com quem o bot está interagindo.
185+
- `pushName`: Nome do contato no WhatsApp.
186+
- `instanceName`: Nome da instância que está executando o bot.
187+
- `serverUrl`: URL do servidor onde a Evolution API está hospedada.
188+
- `apiKey`: Chave de API usada para autenticar as requisições.
189+
190+
### Considerações Finais
191+
192+
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.
193+
194+
## Links Relacionados
195+
196+
- [Chatwoot](https://doc.evolution-api.com/v2/pt/integrations/chatwoot)
197+
- [Typebot](https://doc.evolution-api.com/v2/pt/integrations/typebot)
198+
- [Website](https://evolution-api.com/)
199+
- [GitHub](https://github.com/EvolutionAPI/evolution-api)
200+
201+
---
202+
203+
*Documentação extraída de: https://doc.evolution-api.com/v2/pt/integrations/evolution-bot*

‎evolution-bot-linkpreview-example.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Evolution Bot - Exemplo Prático com LinkPreview
2+
3+
Este exemplo mostra como implementar uma API simples que utiliza o Evolution Bot com controle de link preview.
4+
5+
## 1. Exemplo de API em Node.js/Express
6+
7+
```javascript
8+
const express = require('express');
9+
const app = express();
10+
app.use(express.json());
11+
12+
app.post('/webhook/evolutionbot', (req, res) => {
13+
const { query, inputs } = req.body;
14+
const userMessage = query.toLowerCase();
15+
16+
// Exemplo 1: Mensagem com email (sem preview)
17+
if (userMessage.includes('email')) {
18+
return res.json({
19+
message: `Seu email de confirmação foi enviado para: ${inputs.pushName}@exemplo.com\n\nVerifique sua caixa de entrada.`,
20+
linkPreview: false // ❌ Desabilita preview para evitar poluição visual
21+
});
22+
}
23+
24+
// Exemplo 2: Mensagem com link promocional (com preview)
25+
if (userMessage.includes('promoção')) {
26+
return res.json({
27+
message: `🎉 Promoção especial disponível!\n\nAcesse: https://loja.exemplo.com/promocao`,
28+
linkPreview: true // ✅ Habilita preview para mostrar a página
29+
});
30+
}
31+
32+
// Exemplo 3: Mensagem com múltiplos links (sem preview)
33+
if (userMessage.includes('links')) {
34+
return res.json({
35+
message: `📋 Links importantes:\n\n• Site: https://site.com\n• Suporte: https://help.site.com\n• Contato: contato@site.com`,
36+
linkPreview: false // ❌ Múltiplos links ficariam confusos com preview
37+
});
38+
}
39+
40+
// Exemplo 4: Resposta padrão
41+
return res.json({
42+
message: "Olá! Como posso ajudar você hoje?"
43+
// linkPreview não especificado = true (padrão)
44+
});
45+
});
46+
47+
app.listen(3000, () => {
48+
console.log('API do Evolution Bot rodando na porta 3000');
49+
});
50+
```
51+
52+
## 2. Configuração do Evolution Bot
53+
54+
```json
55+
{
56+
"enabled": true,
57+
"apiUrl": "http://sua-api.com/webhook/evolutionbot",
58+
"apiKey": "sua-chave-opcional",
59+
"triggerType": "all",
60+
"delayMessage": 1000,
61+
"unknownMessage": "Desculpe, não entendi. Digite 'ajuda' para ver as opções."
62+
}
63+
```
64+
65+
## 3. Exemplos de Uso
66+
67+
### ❌ Problema: Mensagem com preview desnecessário
68+
```json
69+
{
70+
"message": "Confirme seu pedido acessando: https://loja.com/pedido/123 ou entre em contato: vendas@loja.com"
71+
// Sem linkPreview = true (padrão) - Vai mostrar preview da URL e do email
72+
}
73+
```
74+
75+
**Resultado:** Mensagem poluída visualmente no WhatsApp.
76+
77+
### ✅ Solução: Desabilitar preview quando necessário
78+
```json
79+
{
80+
"message": "Confirme seu pedido acessando: https://loja.com/pedido/123 ou entre em contato: vendas@loja.com",
81+
"linkPreview": false
82+
}
83+
```
84+
85+
**Resultado:** Mensagem limpa e fácil de ler.
86+
87+
## 4. Casos de Uso Recomendados
88+
89+
### Use `linkPreview: false` quando:
90+
- ✉️ Mensagem contém emails
91+
- 🔗 Múltiplas URLs na mesma mensagem
92+
- 📝 URLs são apenas referências/instruções
93+
- 🏷️ Mensagens curtas onde o preview é maior que o texto
94+
95+
### Use `linkPreview: true` (ou omita) quando:
96+
- 📰 Compartilhamento de artigos/notícias
97+
- 🛒 Links promocionais/produtos
98+
- 🌐 Preview ajuda a dar contexto
99+
- 📱 Único link principal na mensagem
100+
101+
## 5. Exemplo de Implementação em PHP
102+
103+
```php
104+
<?php
105+
header('Content-Type: application/json');
106+
107+
$input = json_decode(file_get_contents('php://input'), true);
108+
$query = strtolower($input['query'] ?? '');
109+
$inputs = $input['inputs'] ?? [];
110+
111+
if (strpos($query, 'email') !== false) {
112+
echo json_encode([
113+
'message' => "Seu email de confirmação: " . $inputs['pushName'] . "@exemplo.com",
114+
'linkPreview' => false
115+
]);
116+
} elseif (strpos($query, 'site') !== false) {
117+
echo json_encode([
118+
'message' => "Visite nosso site: https://exemplo.com",
119+
'linkPreview' => true
120+
]);
121+
} else {
122+
echo json_encode([
123+
'message' => "Como posso ajudar?"
124+
]);
125+
}
126+
?>
127+
```
128+
129+
## 6. Teste da Implementação
130+
131+
Para testar sua implementação:
132+
133+
1. Configure o Evolution Bot com sua `apiUrl`
134+
2. Envie mensagens de teste via WhatsApp
135+
3. Verifique se os previews aparecem/desaparecem conforme esperado
136+
4. Ajuste a lógica da sua API conforme necessário
137+
138+
## 7. Dicas Importantes
139+
140+
- 🔧 **Sempre teste** as mensagens no WhatsApp real para ver o resultado visual
141+
- ⚡ **Performance**: `linkPreview: false` pode carregar mensagens mais rápido
142+
- 📊 **Analytics**: Monitore quais tipos de mensagem têm melhor engajamento
143+
- 🎯 **UX**: Priorize a legibilidade da mensagem sobre a funcionalidade de preview
144+
145+
---
146+
147+
*Este exemplo mostra como implementar o controle de link preview no Evolution Bot de forma prática e eficiente.*

‎send-text-api-documentation.md‎

Whitespace-only changes.

0 commit comments

Comments
 (0)