Skip to content

2.3.8

Latest
Latest

Choose a tag to compare

View all tags
@sosamilton sosamilton released this 17 Feb 03:17
· 3 commits to main since this release
2.3.8
9a3148b

🚀 Overview

Evolution API v2.3.8 introduces major improvements in bot-human coordination, numbered choices for Typebot, enhanced CI/CD workflows, and critical stability fixes. This release focuses on making the coordination layer more robust and configurable while improving the overall developer experience.

📋 What's New

🤖 Bot-Human Coordination Layer

Configurable Coordination System

  • Environment Variables: Global coordination settings with sensible defaults
  • Per-Instance Override: JSON-based configuration per WhatsApp instance
  • Fine-Grained Control: Enable/disable specific coordination features per instance
# New Environment Variables
CHATBOT_COORDINATION_CHECK_AGENT=true
CHATBOT_COORDINATION_AUTO_PAUSE=true
CHATBOT_COORDINATION_AUTO_RESOLVE=true
CHATBOT_COORDINATION_MANAGE_ENABLED=true

REST Management Endpoint

  • Endpoint: POST /chatbot/manage/action/{instanceName}
  • Actions: transfer_human, resolve_bot, pause_bot, resume_bot
  • Health Check: GET /chatbot/manage/status/{instanceName}
  • Real-time Control: Manual override of automated coordination

Chatwoot Integration Enhanced

  • coordinationSettings: New JSONB field in Chatwoot model
  • API Extensions: Enhanced /chatwoot/set and /chatwoot/find endpoints
  • Backward Compatibility: Existing configurations continue to work

🔢 Typebot Numbered Choices

Numeric Reply Support

  • Enhanced Input: Users can reply with numbers (1, 2, 3) instead of full text
  • Automatic Detection: Typebot automatically maps numeric replies to choices
  • Improved UX: Faster response time, reduced typing effort
  • Fallback Support: Maintains compatibility with text-based replies

Documentation & Testing

  • Comprehensive Docs: Implementation guides and testing procedures
  • Examples: Real-world use cases and configuration samples
  • Troubleshooting: Common issues and solutions

🏗️ CI/CD Improvements

GitHub Container Registry (GHCR) Integration

  • Migration from Docker Hub: All images now published to ghcr.io/sosamilton/evolution-api
  • Automatic Authentication: Uses GITHUB_TOKEN - no manual secrets required
  • Multi-Architecture Support: linux/amd64 and linux/arm64 builds
  • Optimized Caching: GitHub Actions cache for faster builds

Workflow Normalization

  • Consistent Actions: All workflows use same action versions
  • Standardized Configuration: Unified build parameters across all workflows
  • Enhanced Performance: Cache optimization and parallel builds
  • Better Debugging: Improved logging and error reporting

🐛 Bug Fixes & Stability

Chatwoot Webhook Timeout

  • Fire-and-Forget Coordination: Non-blocking webhook processing
  • Improved Reliability: Reduced timeout errors in high-load scenarios
  • Better Error Handling: Graceful degradation when webhooks fail

Meta Business API Normalization

  • Execution Order: Chatwoot-first processing (consistent with Baileys)
  • ChatwootIds Fix: Correct assignment of .inbox_id and .conversation_id
  • Cross-Platform Consistency: Uniform behavior across all WhatsApp providers

🔧 Technical Changes

Database Schema Updates

Chatwoot Model Enhancement

-- New field for per-instance coordination settings
ALTER TABLE "Chatwoot" ADD COLUMN "coordinationSettings" JSONB;

Migration Files

  • PostgreSQL: prisma/postgresql-migrations/20250215120000_add_coordination_settings_chatwoot/
  • MySQL: prisma/mysql-migrations/20250215120000_add_coordination_settings_chatwoot/

API Changes

New Endpoints

POST /chatbot/manage/action/{instanceName}
GET /chatbot/manage/status/{instanceName}

Enhanced Endpoints

POST /chatwoot/set/{instanceName}  # + coordinationSettings support
GET /chatwoot/find/{instanceName}  # + coordinationSettings response

Configuration Updates

Environment Variables

# New coordination settings
CHATBOT_COORDINATION_CHECK_AGENT=true
CHATBOT_COORDINATION_AUTO_PAUSE=true
CHATBOT_COORDINATION_AUTO_RESOLVE=true
CHATBOT_COORDINATION_MANAGE_ENABLED=true

# Docker registry (no longer needed)
# DOCKER_USERNAME, DOCKER_PASSWORD (replaced with GITHUB_TOKEN)

📊 Performance Improvements

Build Performance

  • Cache Optimization: GitHub Actions cache reduces build time by ~40%
  • Parallel Processing: Multi-architecture builds run in parallel
  • Layer Caching: Reused Docker layers across builds

Runtime Performance

  • Webhook Processing: Non-blocking coordination reduces response time
  • Memory Optimization: Improved session management in coordination layer
  • Database Queries: Optimized Chatwoot integration queries

🔄 Breaking Changes

Minimal Impact

  • Docker Registry: Images now published to GHCR instead of Docker Hub
    • Old: evoapicloud/evolution-api:2.3.7
    • New: ghcr.io/sosamilton/evolution-api:2.3.8
  • Backward Compatible: All existing configurations continue to work

Migration Required

  • Database: Run migrations for coordinationSettings field
  • Docker Pull: Update registry URL in deployment scripts

🧪 Testing & Quality

Test Coverage

  • Coordination Layer: Comprehensive unit and integration tests
  • Typebot Integration: End-to-end numbered choice testing
  • API Endpoints: Full REST endpoint validation
  • Database Migrations: Schema update testing

Quality Assurance

  • Load Testing: Coordination layer under high concurrent load
  • Compatibility Testing: Multi-provider WhatsApp integration
  • Security Testing: Enhanced authentication and authorization
  • Performance Testing: Response time and memory usage validation

📚 Documentation

New Documentation

  • Coordination Layer Guide: Complete implementation and configuration
  • Typebot Numbered Choices: Usage examples and best practices
  • CI/CD Migration Guide: Docker Hub to GHCR transition
  • API Reference: Updated endpoints and configuration options

Updated Documentation

  • Installation Guide: GHCR image deployment instructions
  • Configuration Guide: New environment variables and settings
  • Troubleshooting Guide: Common coordination issues and solutions

🚦 Upgrade Instructions

From v2.3.7 to v2.3.8

1. Database Migration

# Run database migrations
npm run db:migrate:dev  # Development
npm run db:deploy      # Production

2. Update Docker Image

# Pull new image from GHCR
docker pull ghcr.io/sosamilton/evolution-api:2.3.8

# Update docker-compose.yml
image: ghcr.io/sosamilton/evolution-api:2.3.8

3. Environment Configuration

# Add new coordination environment variables (optional)
CHATBOT_COORDINATION_CHECK_AGENT=true
CHATBOT_COORDINATION_AUTO_PAUSE=true
CHATBOT_COORDINATION_AUTO_RESOLVE=true
CHATBOT_COORDINATION_MANAGE_ENABLED=true

4. Verify Installation

# Check coordination endpoint
curl http://localhost:8085/chatbot/manage/status/{instanceName}

# Verify Typebot numbered choices
# Test with numeric replies (1, 2, 3) in Typebot conversations

🐛 Known Issues

Resolved Issues

  • ✅ Chatwoot webhook timeout errors
  • ✅ Meta Business API execution order inconsistency
  • ✅ ChatwootIds assignment bugs
  • ✅ Docker Hub authentication failures

Limitations

  • Database Migration: Requires manual execution for existing installations
  • Docker Registry: Requires update of deployment scripts
  • Configuration: New environment variables are optional but recommended

🙏 Acknowledgments

Contributors

  • @sosamilton (Milton Sosa): Lead development and architecture
  • Community Contributors: Bug reports, testing, and feedback

Special Thanks

  • Chatwoot Team: Integration support and API improvements
  • Typebot Community: Feature requests and testing feedback
  • Beta Testers: Real-world validation and performance testing

🔮 What's Next

Planned for v2.3.9

  • Web Flows Enhanced: Hybrid chat-web form integration
  • Advanced Analytics: Coordination layer metrics and insights
  • Performance Optimization: Further memory and speed improvements
  • Enhanced Security: Additional authentication and authorization features

Long-term Roadmap

  • AI-Powered Coordination: Intelligent bot-human handoff decisions
  • Multi-Language Support: Extended localization capabilities
  • Advanced Monitoring: Real-time performance and health monitoring
  • API v3 Preparation: Next-generation API architecture planning

📞 Support

Getting Help

Enterprise Support

  • Priority Support: Available for enterprise customers
  • Custom Development: Tailored solutions and integrations
  • Training & Onboarding: Team education and best practices

Release Date: February 17, 2026
Version: 2.3.8
Compatibility: v2.3.x series
Support: Active maintenance and community support

This release represents a significant step forward in making Evolution API more robust, configurable, and developer-friendly while maintaining backward compatibility and stability.

Full Changelog: v2.3.8...2.3.8

Contributors

sosamilton
Assets 2
Loading