mirror of
https://github.com/EvolutionAPI/evolution-api.git
synced 2025-12-11 19:09:39 -06:00
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
This commit is contained in:
Anderson Silva
parent
02b81beb7a
commit
ceddace915
@ -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*
|
|
||||||
@ -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.*
|
|
||||||
Loading…
Reference in New Issue
Block a user