Como o sistema funciona
- WhatsApp recebe a mensagem do cliente.
- Evolution API captura o evento.
- A Evolution chama o webhook do LinkZap.
- O LinkZap decide a resposta (menu, IA ou humano).
- A Evolution envia a resposta de volta no WhatsApp.
Se o webhook não estiver apontando para o LinkZap, o bot não responde — mesmo com o QR conectado.
Nome amigável × ID Evolution
No painel você vê um nome fácil (ex.: teste). Na Evolution o nome técnico é outro (ex.: teste-mrrbyy6e).
- Use o nome amigável no dia a dia do painel.
- Use o ID Evolution no Manager, Insomnia e chamadas diretas à API.
- O ID aparece abaixo do status e pode ser copiado.
Passo a passo para o bot responder
- Clique em Conectar número e escaneie o QR.
- Espere o status Conectado.
- Configure o menu e salve.
- Na aba Conectar, use Testar API para enviar uma mensagem e validar o envio.
- De outro celular, mande
oioumenupara o número conectado.
Comandos do cliente no WhatsApp
| Cliente digita | O que acontece |
|---|---|
oi, olá, menu, inicio | Mostra o menu |
1, 2, 3… | Resposta da opção do menu |
oi, alo, bom dia… (modo automático) | Abre o menu |
número da opção (ex.: 1) | Executa aquela opção do menu |
palavra de transferência (ex.: humano) ou opção “Transfere para humano” | Pausa o bot e vai para o Inbox |
bot (no modo humano) | Reativa o atendimento automático |
| qualquer outra mensagem no modo humano (ex.: boa noite, ok, menu) | Aparece no Inbox para o atendente |
| qualquer outro texto | IA (se ligada) ou o menu de novo |
Testar a API pelo painel
Na aba 1. Conectar → bloco Testar API:
- Número com DDI, sem espaços:
5521999999999 - Clique em Enviar teste
- Se a mensagem chegar no destino, a Evolution está enviando corretamente
Usar a Evolution API diretamente (Insomnia / Postman)
Base: URL da Evolution (ex.: https://linkzapapi.seusite.com.br)
Header obrigatório (sem espaço no nome):
apikey: SUA_EVOLUTION_API_KEY
Enviar texto — use o ID Evolution completo na URL:
POST /message/sendText/{id-evolution}
Content-Type: application/json
{
"number": "5521999999999",
"text": "Olá, teste"
}
Erros comuns:
- 404 — usou o nome curto (
teste) em vez do ID completo - 401 — faltou ou errou o header
apikey - 400 nginx — espaço no nome do header (
apikey :)
Webhook (para o bot responder sozinho)
A Evolution deve chamar:
POST {APP_URL}/api/webhook/evolution?secret={EVOLUTION_WEBHOOK_SECRET}
Eventos: MESSAGES_UPSERT, CONNECTION_UPDATE, QRCODE_UPDATED.
Health check (deve retornar ok: true):
GET {APP_URL}/api/webhook/evolution
APP_URL precisa ser a URL pública do LinkZap (HTTPS), nunca localhost em produção.
API do LinkZap (painel / integração)
| Método | Rota | Descrição |
|---|---|---|
| POST | /api/auth/login | Login (retorna JWT) |
| GET | /api/instances | Listar números |
| POST | /api/instances | Criar + gerar QR |
| POST | /api/instances/:id/qr | Atualizar QR |
| GET | /api/instances/:id/status | Status da conexão |
| POST | /api/instances/:id/test-message | Enviar mensagem de teste |
| POST | /api/instances/:id/webhook | Regravar webhook na Evolution |
| PUT | /api/bots/:id | Salvar menu / IA |
| POST | /api/webhook/evolution | Recebe eventos da Evolution |
Rotas autenticadas usam header Authorization: Bearer SEU_JWT.
Checklist se não estiver respondendo
- Status da instância = Conectado?
- Testar API enviou a mensagem?
- Webhook sincronizado (botão acima) e URL pública correta?
- Mensagem de teste veio de outro celular (não do próprio número conectado)?
- Cliente digitou
oioumenu?