Evolution Whatsapp

Name: Evolution Whatsapp
Rating: 3.5 (1 reviews)
Author: tiagonucleo

By tiagonucleo 👁 82 views ▲ 0 votes

OpenClaw channel plugin for WhatsApp messages delivered by Evolution API webhooks.

GitHub

Install

openclaw plugins install @ti_c_silva/[email protected]

Configuration Example

{
  "plugins": {
    "allow": ["evolution-whatsapp"],
    "entries": {
      "evolution-whatsapp": {
        "enabled": true
      }
    }
  },
  "channels": {
    "evolution-whatsapp": {
      "enabled": true,
      "apiBaseUrl": "https://evolution.example.com",
      "instanceName": "Auto-n8n",
      "apiKey": { "source": "env", "provider": "default", "id": "EVOLUTION_API_KEY" },
      "webhookSecret": { "source": "env", "provider": "default", "id": "EVOLUTION_WEBHOOK_SECRET" },
      "webhookPath": "/webhook/evolution-whatsapp",
      "webhookSecretHeader": "x-openclaw-evolution-secret",
      "dmPolicy": "allowlist",
      "allowFrom": ["+5500000000000"],
      "ignoreGroups": true,
      "sendBodyMode": "textMessageWithFallback",
      "linkPreview": false
    }
  }
}

README

# OpenClaw Evolution WhatsApp

Canal OpenClaw para mensagens WhatsApp recebidas por webhooks da Evolution API.

## Instalacao

```bash
openclaw plugins install @ti_c_silva/[email protected]
```

## Objetivo

Este plugin substitui a tentativa de parear o WhatsApp Web do OpenClaw quando o
WhatsApp Business recusa novo linked-device. A Evolution continua proprietaria
da sessao WhatsApp, e o OpenClaw recebe apenas os eventos autorizados pelo
webhook.

## Fluxo

1. Evolution envia `messages.upsert` para o gateway OpenClaw.
2. O plugin valida o header secreto configurado.
3. O plugin ignora mensagens `fromMe`, grupos por padrao e remetentes fora da
   allowlist.
4. A mensagem e despachada pelo pipeline oficial do OpenClaw.
5. A resposta do agente volta para a Evolution por
   `POST /message/sendText/{instanceName}`.

## Configuracao OpenClaw

Exemplo sanitizado:

```json
{
  "plugins": {
    "allow": ["evolution-whatsapp"],
    "entries": {
      "evolution-whatsapp": {
        "enabled": true
      }
    }
  },
  "channels": {
    "evolution-whatsapp": {
      "enabled": true,
      "apiBaseUrl": "https://evolution.example.com",
      "instanceName": "Auto-n8n",
      "apiKey": { "source": "env", "provider": "default", "id": "EVOLUTION_API_KEY" },
      "webhookSecret": { "source": "env", "provider": "default", "id": "EVOLUTION_WEBHOOK_SECRET" },
      "webhookPath": "/webhook/evolution-whatsapp",
      "webhookSecretHeader": "x-openclaw-evolution-secret",
      "dmPolicy": "allowlist",
      "allowFrom": ["+5500000000000"],
      "ignoreGroups": true,
      "sendBodyMode": "textMessageWithFallback",
      "linkPreview": false
    }
  }
}
```

Secrets aceitos pelo plugin:

- `EVOLUTION_API_KEY`
- `EVOLUTION_WEBHOOK_SECRET`
- SecretRef em `channels.evolution-whatsapp.apiKey`
- SecretRef em `channels.evolution-whatsapp.webhookSecret`

Nunca salvar esses valores no Git.

## Configuracao Evolution

No webhook da instancia:

- URL: `https://<openclaw-host>/webhook/evolution-whatsapp`
- Metodo: `POST`
- Eventos: `MESSAGES_UPSERT` ou equivalente `messages.upsert`
- Header customizado: nome igual a `webhookSecretHeader`, valor igual a
  `EVOLUTION_WEBHOOK_SECRET`

## Health check

```bash
curl https://<openclaw-host>/webhook/evolution-whatsapp/health
```

Resposta esperada:

```json
{"status":"ok","channel":"evolution-whatsapp"}
```

## Rollback

1. Desativar o webhook Evolution que aponta para `/webhook/evolution-whatsapp`.
2. Desabilitar `channels.evolution-whatsapp.enabled`.
3. Remover `evolution-whatsapp` de `plugins.allow` se necessario.
4. Reiniciar o gateway OpenClaw.

Nao reativar o endpoint antigo do `assistente-pessoal-ai` sem aprovacao humana
explicita, para evitar mistura de projetos.

channels