https://github.com/evolution-foundation/evo-bot-runtime
https://github.com/evolution-foundation/evo-bot-runtime
Last synced: 23 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/evolution-foundation/evo-bot-runtime
- Owner: evolution-foundation
- License: apache-2.0
- Created: 2026-03-04T18:53:57.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T18:32:12.000Z (25 days ago)
- Last Synced: 2026-05-25T20:28:22.661Z (25 days ago)
- Language: Go
- Size: 25.7 MB
- Stars: 2
- Watchers: 0
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
README
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](https://github.com/evolution-foundation/evo-crm-community) ecosystem maintained by Evolution Foundation. To use the full stack, clone the umbrella repository with submodules:
```bash
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
```bash
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
```bash
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:
```bash
# 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](https://evolutionfoundation.com.br) |
| Documentation | [docs.evolutionfoundation.com.br](https://docs.evolutionfoundation.com.br) |
| Community | [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community) |
| Changelog | [CHANGELOG.md](./CHANGELOG.md) |
| Contributing | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| Security | [SECURITY.md](./SECURITY.md) |
---
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to submit issues, propose features, and open pull requests.
Join our [community](https://evolutionfoundation.com.br/community) to discuss ideas and collaborate.
---
## Security
For security issues, **do not open a public issue**. Email **suporte@evofoundation.com.br** or use GitHub's private vulnerability reporting. See [SECURITY.md](./SECURITY.md) for details.
---
## License
Evo Bot Runtime is licensed under the Apache License 2.0. See [LICENSE](./LICENSE) for details.
## Trademarks
"Evolution Foundation", "Evolution" and "Evo Bot Runtime" are trademarks of Evolution Foundation. See [TRADEMARKS.md](./TRADEMARKS.md) for the brand assets policy.
Third-party attributions are documented in [NOTICE](./NOTICE).
---
Made by Evolution Foundation · © 2026