README.md

May 6, 2026 · View on GitHub

Evo Bot Runtime

Bot pipeline execution, debouncing, and dispatch service for the Evo CRM Community ecosystem.

Website · Documentation · Community · Support

About

Evo Bot Runtime is the bot orchestration service for the Evo CRM Community ecosystem. Built in Go with the Gin framework, it manages bot pipeline execution, message debouncing, and dispatch coordination across multiple WhatsApp instances and AI agents.

It integrates with evo-ai-processor-community (agent execution), evo-ai-crm-community (conversations) and Evolution API / Evolution Go (WhatsApp providers) to deliver real-time conversational flows with sub-second latency.

Part of the Evo CRM Community

Evo Bot Runtime is part of the Evo CRM Community ecosystem maintained by Evolution Foundation. To use the full stack, clone the umbrella repository with submodules:

git clone --recurse-submodules git@github.com:evolution-foundation/evo-crm-community.git

The Community Edition is single-tenant by design — one account, no multi-tenancy overhead, no super-admin, no billing or plans. All limits are removed and features are unlocked by default.

Quick Start

Prerequisites

Go 1.24+
PostgreSQL 12+
Redis 6+
Docker (optional, recommended for production)

Installation

git clone git@github.com:evolution-foundation/evo-bot-runtime.git
cd evo-bot-runtime

# Install dependencies
go mod download

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run
make run

The service will be available at http://localhost:8080.

Docker

docker build -t evo-bot-runtime .
docker run -p 8080:8080 --env-file .env evo-bot-runtime

Configuration

Copy .env.example to .env and configure the required variables:

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/evo_bot_runtime

# Redis (for debouncing and pipeline state)
REDIS_URL=redis://localhost:6379/0

# Service URLs
EVO_AI_PROCESSOR_URL=http://localhost:8000
EVO_AI_CRM_URL=http://localhost:3000

# Authentication (Bearer token from evo-auth-service-community)
JWT_SECRET_KEY=your_evolution_secret_key

See .env.example for the full list of variables.

Architecture

Evo Bot Runtime sits between WhatsApp providers and AI agent execution:

WhatsApp message
      ↓
Evolution API / Evolution Go
      ↓
Evo Bot Runtime (debounce + pipeline)
      ↓
Evo AI Processor (agent execution)
      ↓
Evo CRM (conversation persistence)

Key responsibilities:

Debouncing: groups rapid-fire messages from the same contact into a single agent invocation
Pipeline execution: runs ordered bot flows with branching logic
Dispatch: routes responses back to the originating WhatsApp instance
State: persists pipeline progress in Redis with PostgreSQL fallback

Documentation

Resource	Link
Website	evolutionfoundation.com.br
Documentation	docs.evolutionfoundation.com.br
Community	evolutionfoundation.com.br/community
Changelog	CHANGELOG.md
Contributing	CONTRIBUTING.md
Security	SECURITY.md