Community Integration: WhatsApp via Evolution API — agent tools + auto-reply bot

[m0tekferreira-code]

O que esta integração adiciona

Implementei suporte nativo a WhatsApp no Odysseus usando a Evolution API como gateway. O agente ganha 4 novas tools (whatsapp_send_message, whatsapp_list_chats, whatsapp_read_messages, whatsapp_search) e um bot de auto-resposta que processa mensagens WhatsApp recebidas através do loop completo do Odysseus.

Funcionalidade	Descrição
Agent tools	4 tools que o agente chama nativamente: listar chats, ler mensagens, enviar, buscar
Webhook de entrada	Evolution API envia cada mensagem recebida ao Odysseus; o agente auto-responde (opcional)
Cache SQLite local	Todas as mensagens salvas em data/whatsapp.db para busca e histórico
RAG indexado	As 4 tools são embedadas no índice vetorial para seleção automática
Detecção de intent	Keywords como "whatsapp", "zap", "wpp" ativam o domínio correto
Model-agnostic	Funciona com qualquer endpoint OpenAI-compatible (GLM, Claude, GPT-4, Qwen, etc.)

---

Arquitetura

User: "send a WhatsApp to Gabriel"
         │
         ▼
Odysseus agent (intent: "whatsapp" domain detected)
         │
         ├─► whatsapp_send_message tool
         │         │
         │         ▼
         │   POST /api/whatsapp/send
         │         │
         │         ▼
         │   Evolution API  →  WhatsApp
         │
Incoming WhatsApp message (webhook from Evolution)
         │
         ▼
POST /api/whatsapp/webhook
         ├─ saves to SQLite (data/whatsapp.db)
         └─ if sender authorized → stream_agent_loop() → auto-reply

---

Arquivos modificados / criados

Novo: routes/whatsapp_routes.py (~270 linhas)

Config via env vars:

EVOLUTION_URL      = os.environ.get("EVOLUTION_API_URL",  "https://your-evolution-instance.com")
EVOLUTION_KEY      = os.environ.get("EVOLUTION_API_KEY",  "your-api-key")
EVOLUTION_INSTANCE = os.environ.get("EVOLUTION_INSTANCE", "your-instance-name")
WA_DB_PATH         = Path(os.environ.get("ODYSSEUS_DATA_DIR", "data")) / "whatsapp.db"
WA_BOT_ENABLED     = os.environ.get("WA_BOT_ENABLED", "true").lower() == "true"
WA_ALLOWED_SENDERS = set(filter(None, os.environ.get("WA_ALLOWED_SENDERS", "").split(",")))

Endpoints registrados:

Method	Path	Descrição
POST	/api/whatsapp/webhook	Recebe eventos da Evolution API
GET	/api/whatsapp/chats	Lista chats recentes (do SQLite)
GET	/api/whatsapp/messages/{jid}	Histórico de conversa
POST	/api/whatsapp/send	Envia mensagem via Evolution API
GET	/api/whatsapp/status	Status da conexão + stats do DB
GET/POST	/api/whatsapp/config	Configuração por instância
GET	/api/whatsapp/models	Lista modelos LLM disponíveis

Modificado: app.py

from routes.whatsapp_routes import setup_whatsapp_routes
app.include_router(setup_whatsapp_routes())

# Auth-exempt (Evolution webhook não tem session token):
"/api/whatsapp/webhook",
"/api/whatsapp/status",
"/api/whatsapp/models",

Modificado: src/tool_schemas.py

4 schemas adicionados ao FUNCTION_TOOL_SCHEMAS:

{"type": "function", "function": {
    "name": "whatsapp_list_chats",
    "description": "List recent WhatsApp conversations.",
    "parameters": {"type": "object", "properties": {
        "limit": {"type": "integer", "description": "Max chats (default 30)"}
    }}
}},
{"type": "function", "function": {
    "name": "whatsapp_read_messages",
    "description": "Read messages from a WhatsApp conversation by JID or phone number.",
    "parameters": {"type": "object",
        "properties": {
            "jid": {"type": "string"},
            "limit": {"type": "integer"}
        }, "required": ["jid"]
    }
}},
{"type": "function", "function": {
    "name": "whatsapp_send_message",
    "description": "Send a WhatsApp message to a contact.",
    "parameters": {"type": "object",
        "properties": {
            "jid": {"type": "string"},
            "message": {"type": "string"}
        }, "required": ["jid", "message"]
    }
}},
{"type": "function", "function": {
    "name": "whatsapp_search",
    "description": "Search WhatsApp messages by keyword across all conversations.",
    "parameters": {"type": "object",
        "properties": {
            "query": {"type": "string"},
            "limit": {"type": "integer"}
        }, "required": ["query"]
    }
}},

Modificado: src/tool_implementations.py

async def do_whatsapp_tool(tool_name: str, content: str, owner=None) -> dict:
    import json as _j, sqlite3
    from pathlib import Path
    from urllib.parse import quote
    args = _j.loads(content) if content and content.strip() else {}

    async def _api(path, method="GET", body=None):
        payload = {"path": path, "method": method}
        if body: payload["body"] = body
        return await do_app_api(_j.dumps(payload), owner=owner)

    if tool_name == "whatsapp_list_chats":
        return await _api(f"/api/whatsapp/chats?limit={int(args.get('limit', 30))}")

    elif tool_name == "whatsapp_read_messages":
        jid = str(args.get("jid", ""))
        if "@" not in jid:
            jid = jid.strip().replace("+","").replace(" ","").replace("-","") + "@s.whatsapp.net"
        return await _api(f"/api/whatsapp/messages/{quote(jid, safe='')}?limit={int(args.get('limit', 40))}")

    elif tool_name == "whatsapp_send_message":
        jid = str(args.get("jid", ""))
        if "@" not in jid:
            jid = jid.strip().replace("+","").replace(" ","").replace("-","") + "@s.whatsapp.net"
        return await _api("/api/whatsapp/send", "POST", {"jid": jid, "text": args.get("message", "")})

    elif tool_name == "whatsapp_search":
        query = args.get("query", "")
        limit = int(args.get("limit", 20))
        db_path = Path(os.environ.get("ODYSSEUS_DATA_DIR", "data")) / "whatsapp.db"
        conn = sqlite3.connect(str(db_path))
        conn.row_factory = sqlite3.Row
        rows = conn.execute(
            "SELECT remote_jid, push_name, from_me, content, timestamp FROM wa_messages "
            "WHERE content LIKE ? ORDER BY timestamp DESC LIMIT ?",
            (f"%{query}%", limit)
        ).fetchall()
        conn.close()
        return {"result": [dict(r) for r in rows], "count": len(rows)}

Modificado: src/tool_execution.py

from src.tool_implementations import (..., do_whatsapp_tool)

elif tool in ("whatsapp_list_chats", "whatsapp_read_messages",
              "whatsapp_send_message", "whatsapp_search"):
    result = await do_whatsapp_tool(tool, content, owner=owner)

Modificado: src/agent_tools/__init__.py

TOOL_TAGS = {
    ...,
    "whatsapp_list_chats", "whatsapp_read_messages",
    "whatsapp_send_message", "whatsapp_search",
}

Modificado: src/tool_index.py

# BUILTIN_TOOL_DESCRIPTIONS (RAG vector index):
"whatsapp_list_chats": "List recent WhatsApp conversations. Use when user asks to see conversations or WhatsApp history.",
"whatsapp_read_messages": "Read messages from a specific WhatsApp conversation by JID or phone number.",
"whatsapp_send_message": "Send a WhatsApp message to a contact or phone number.",
"whatsapp_search": "Search WhatsApp messages by keyword across all conversations.",

# _KEYWORD_HINTS (fallback when RAG unavailable):
frozenset({"whatsapp", "zap", "wpp", "whatsapp message", "send whatsapp",
           "whatsapp history", "whatsapp conversations"}):
    {"whatsapp_list_chats", "whatsapp_read_messages",
     "whatsapp_send_message", "whatsapp_search"},

Modificado: src/agent_loop.py

# a) _model_supports_tools — adicionar glm-5 se usar GLM-5.x:
"glm-4", "glm-5", "internlm", "hermes",

# b) _DOMAIN_RULES:
"whatsapp": """\
## WhatsApp rules
- To send, read, or search WhatsApp messages use the whatsapp_* tools.
- whatsapp_send_message: send message. whatsapp_list_chats: list chats.
- whatsapp_read_messages: read history. whatsapp_search: search by keyword.""",

# c) _DOMAIN_TOOL_MAP:
"whatsapp": {"whatsapp_list_chats", "whatsapp_read_messages",
             "whatsapp_send_message", "whatsapp_search"},

# d) Intent detection (inside _analyze_intent, after "settings" check):
if has(r"whatsapp|zap|wpp"):
    domains.add("whatsapp")

Modificado: src/tool_policy.py

_COMMON_TOOL_NAMES = {
    ...,
    "whatsapp_list_chats",
    "whatsapp_read_messages",
    "whatsapp_search",
    "whatsapp_send_message",
}

---

Variáveis de ambiente

EVOLUTION_API_URL=https://your-evolution-instance.com
EVOLUTION_API_KEY=your-api-key-here
EVOLUTION_INSTANCE=your-instance-name
WA_BOT_ENABLED=true
WA_ALLOWED_SENDERS=5541XXXXXXXXX,5541YYYYYYYYY

---

SQLite schema

CREATE TABLE wa_messages (
    id TEXT PRIMARY KEY, instance TEXT NOT NULL,
    remote_jid TEXT NOT NULL, from_me INTEGER NOT NULL DEFAULT 0,
    push_name TEXT, msg_type TEXT, content TEXT,
    timestamp INTEGER, created_at TEXT DEFAULT (datetime('now'))
);
CREATE INDEX idx_wa_jid_ts ON wa_messages(instance, remote_jid, timestamp DESC);
CREATE TABLE wa_config (key TEXT PRIMARY KEY, value TEXT);

---

Lições aprendidas — registrar tool em 7 lugares

Ao adicionar uma nova tool no Odysseus, registre em todos estes pontos ou ela ficará invisível ao agente:

1. FUNCTION_TOOL_SCHEMAS — schema JSON para function calling
2. TOOL_TAGS — reconhecimento em fenced-block parsing
3. tool_execution.py dispatcher — execução
4. BUILTIN_TOOL_DESCRIPTIONS — indexação no ChromaDB (RAG)
5. _KEYWORD_HINTS — fallback por keywords
6. _DOMAIN_TOOL_MAP — injeção determinística por domínio
7. _DOMAIN_RULES — prompt de instruções do domínio
8. _COMMON_TOOL_NAMES — pool de tools conhecidas na policy
9. Intent detection em _analyze_intent() — sem isso low_signal=True e o RAG é pulado

Ponto crítico: se low_signal=True (nenhum domínio detectado), o Odysseus usa apenas {ask_user, manage_memory, update_plan} e ignora o RAG completamente. A detecção de intent (item 9) é o gatilho de tudo.

---

Integração desenvolvida por Edson Ferreira. Testado no Odysseus (commit Jun 2026) com Evolution API v2 e modelos GLM-5.1 / GLM-4.7-flash.