NeoAnd/evolution-api
1
0
Fork 0
mirror of https://github.com/EvolutionAPI/evolution-api.git synced 2025-12-09 09:59:40 -06:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

chore: remove documentation .md files

Browse Source 
- Remove evolution-bot-documentation.md
- Remove evolution-bot-linkpreview-example.md
- Remove send-text-api-documentation.md
- Keep only the core linkPreview implementation
This commit is contained in:
Anderson Silva 2025-09-03 19:59:24 -03:00
parent 02b81beb7a
commit ceddace915
3 changed files with 0 additions and 350 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
evolution-bot-documentation.md
View File

@ -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*

147
evolution-bot-linkpreview-example.md
View File

@ -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
<?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.*

0
send-text-api-documentation.md
View File