EvoAI Integration

EvoAI is Evolution API’s native AI agent platform designed specifically for WhatsApp automation. It provides intelligent conversation handling, context awareness, and seamless integration with the Evolution API ecosystem.

What is EvoAI?

EvoAI offers:

Native integration with Evolution API
Intelligent conversation routing
Context-aware responses
Multi-language support
Custom agent configuration
Advanced NLU capabilities
Seamless session management
Built-in analytics and insights

Enable EvoAI Integration

Add this environment variable to your .env file:

# Enable EvoAI integration
EVOAI_ENABLED=true

Configuration Settings

Create Default Settings

Before creating EvoAI agents, configure default behavior settings for your instance.

curl -X POST https://your-api.com/evoai/settings/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "I did not understand your message.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10,
    "ignoreJids": [],
    "evoaiIdFallback": ""
  }'

Settings Parameters

expire

number

required

Session expiration time in seconds. Default: 300 (5 minutes)

keywordFinish

string

required

Keyword to terminate the bot session. Example: “#EXIT”, “bye”

delayMessage

number

required

Delay in milliseconds between messages. Default: 1000

unknownMessage

string

required

Message sent when agent encounters an error or cannot respond

listeningFromMe

boolean

required

Whether agent responds to messages sent by the instance owner

stopBotFromMe

boolean

required

Whether instance owner can stop the agent session

keepOpen

boolean

required

Keep session open after completion. Default: false

debounceTime

number

required

Seconds to wait before processing rapid messages. Default: 10

ignoreJids

array

required

List of JIDs (phone numbers) to ignore

evoaiIdFallback

string

Fallback EvoAI agent ID to use when primary agent fails

Create an EvoAI Agent

Get EvoAI credentials

Obtain your EvoAI agent URL and API key from the EvoAI platform.

Create agent in Evolution API

Test the integration

Send a message matching your trigger to start an EvoAI conversation.

curl -X POST https://your-api.com/evoai/create/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Customer Service Agent",
    "agentUrl": "https://evoai.yourdomain.com/agent/customer-service",
    "apiKey": "your-evoai-api-key",
    "triggerType": "keyword",
    "triggerOperator": "equals",
    "triggerValue": "agent",
    "expire": 300,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "Sorry, I encountered an error.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 10
  }'

Request Parameters

enabled

boolean

required

Enable or disable this agent

description

string

required

Description of the agent purpose

agentUrl

string

required

EvoAI agent endpoint URL

apiKey

string

required

Your EvoAI API key for authentication

triggerType

string

required

Trigger type: “all”, “keyword”, or “advanced”

triggerOperator

string

For keyword triggers: “equals”, “contains”, “startsWith”, “endsWith”, “regex”

triggerValue

string

The keyword or regex pattern to trigger this agent

Trigger Types

All Messages

Respond to every message (only one “all” trigger allowed per instance):

{
  "triggerType": "all"
}

Keyword Trigger

Trigger based on specific keywords:

{
  "triggerType": "keyword",
  "triggerOperator": "equals",
  "triggerValue": "support"
}

Available operators:

equals - Exact match
contains - Contains the keyword
startsWith - Message starts with keyword
endsWith - Message ends with keyword
regex - Regular expression match

Advanced Trigger

Use regex for complex pattern matching:

{
  "triggerType": "advanced",
  "triggerValue": "^(help|support|assist)\\s"
}

Update EvoAI Agent

Modify an existing EvoAI agent configuration:

curl -X PUT https://your-api.com/evoai/update/{instance}/{botId} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Updated Service Agent",
    "triggerValue": "help"
  }'

Delete EvoAI Agent

Remove an EvoAI agent from your instance:

curl -X DELETE https://your-api.com/evoai/delete/{instance}/{botId} \
  -H "apikey: your-api-key"

Fetch EvoAI Agents

Retrieve all EvoAI agents configured for your instance:

curl -X GET https://your-api.com/evoai/fetch/{instance} \
  -H "apikey: your-api-key"

Session Management

Change Session Status

Update the status of an active EvoAI session:

curl -X POST https://your-api.com/evoai/changeStatus/{instance} \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "[email protected]",
    "status": "closed"
  }'

Fetch Sessions

Get all active EvoAI sessions:

curl -X GET https://your-api.com/evoai/fetchSessions/{instance} \
  -H "apikey: your-api-key"

EvoAI Features

Native Evolution API Integration

EvoAI is built specifically for Evolution API:

Seamless authentication and authorization
Optimized for WhatsApp message formats
Native support for Evolution API events
Integrated session management
Built-in Evolution API context awareness

Intelligent Conversation Handling

Advanced conversation capabilities:

Context retention across messages
Intent recognition and classification
Entity extraction from messages
Sentiment analysis
Multi-turn conversation support
Conversation history tracking

Multi-Language Support

Global reach with language detection:

Automatic language detection
Multi-language response generation
Language-specific knowledge bases
Translation capabilities
Localized conversation flows

Analytics and Insights

Built-in monitoring and analytics:

Conversation metrics and KPIs
User engagement tracking
Agent performance monitoring
Error and exception tracking
Custom event logging

Use Cases

Intelligent Customer Support

Deploy smart support agents:

Automated issue resolution
Intelligent ticket routing
FAQ automation
Escalation to human agents
Follow-up and feedback collection

Sales Automation

Enhance sales processes:

Lead qualification and scoring
Product recommendations
Order processing and tracking
Upsell and cross-sell automation
Customer journey optimization

Appointment Scheduling

Automate booking processes:

Availability checking
Appointment booking and confirmation
Reminder notifications
Rescheduling and cancellations
Calendar integration

Information Delivery

Provide instant information:

Knowledge base queries
Product information
Service status updates
Account information
Personalized recommendations

Best Practices

EvoAI agents are optimized for WhatsApp’s conversational format. Keep responses concise and actionable.

Monitor your agent’s performance regularly and update configurations based on user interactions and feedback.

Design clear conversation flows: Map out expected user journeys
Set appropriate timeouts: Balance responsiveness with session management
Use fallback agents: Configure fallback options for error handling
Monitor performance: Track metrics and optimize based on insights
Test thoroughly: Validate agent behavior with various scenarios
Update regularly: Keep agent knowledge and responses current
Handle edge cases: Plan for unexpected inputs and errors

Troubleshooting

Agent not responding

Verify EVOAI_ENABLED=true in environment
Check that the agent is enabled (enabled: true)
Ensure trigger conditions match the incoming message
Verify EvoAI agent URL is accessible
Check API key is valid and has proper permissions
Review EvoAI platform logs for errors

Slow response times

Check EvoAI platform performance
Verify network latency between Evolution API and EvoAI
Optimize agent configuration for faster processing
Monitor concurrent session load
Review agent complexity and simplify if needed

Context not maintained

Increase expire time for longer sessions
Set keepOpen: true for persistent conversations
Verify session IDs are being tracked correctly
Check EvoAI conversation memory settings
Review session management configuration

Authentication errors

Verify API key is correct and active
Check API key permissions in EvoAI platform
Ensure agent URL is properly configured
Test authentication with curl or Postman
Review EvoAI platform access logs

Advanced Configuration

Multiple Agents

Deploy specialized agents for different purposes:

// Sales agent
{
  agentUrl: 'https://evoai.example.com/agent/sales',
  triggerType: 'keyword',
  triggerValue: 'buy'
}

// Support agent
{
  agentUrl: 'https://evoai.example.com/agent/support',
  triggerType: 'keyword',
  triggerValue: 'help'
}

// General assistant (fallback)
{
  agentUrl: 'https://evoai.example.com/agent/general',
  triggerType: 'all'
}

Fallback Configuration

Configure fallback agents for error handling:

{
  "evoaiIdFallback": "fallback-agent-id"
}

When the primary agent fails or encounters an error, the fallback agent takes over automatically.

Integration with Evolution API Features

Webhook Events

EvoAI agents work seamlessly with Evolution API webhooks:

Receive all message events
Access full message context
Integrate with other Evolution API features
Subscribe to custom events

Multi-Instance Support

Deploy agents across multiple instances:

Instance-specific configurations
Shared agent resources
Centralized management
Isolated sessions per instance

Session Persistence

Manage long-running conversations:

Persistent session storage
Context preservation across restarts
Session recovery mechanisms
Custom session attributes

Performance Optimization

Response Time

Optimize for fast responses:

Use edge locations for EvoAI deployment
Cache frequently accessed data
Implement request batching
Optimize agent logic

Scalability

Handle high volumes:

Load balancing across agent instances
Horizontal scaling capabilities
Queue management for peak loads
Resource allocation optimization

Monitoring

Track performance metrics:

Response time monitoring
Success rate tracking
Error rate analysis
Resource utilization metrics

Security

API Key Management

Rotate API keys regularly
Use environment-specific keys
Implement key expiration policies
Monitor API key usage

Data Privacy

Encrypt sensitive data in transit and at rest
Implement data retention policies
Comply with privacy regulations (GDPR, LGPD, etc.)
Anonymize personal information when possible

Access Control

Implement role-based access control
Audit agent access and usage
Restrict agent permissions
Monitor unauthorized access attempts

OpenAI - OpenAI GPT models
Dify - LLM orchestration platform
Flowise - Visual AI workflow builder
N8N - Workflow automation

Get Started

Core Concepts

WhatsApp Integration

Chatbot Integrations

Event Systems

Storage & Media

Deployment

​EvoAI Integration

​What is EvoAI?

​Enable EvoAI Integration

​Configuration Settings

​Create Default Settings

​Settings Parameters

​Create an EvoAI Agent

​Request Parameters

​Trigger Types

​All Messages

​Keyword Trigger

​Advanced Trigger

​Update EvoAI Agent

​Delete EvoAI Agent

​Fetch EvoAI Agents

​Session Management

​Change Session Status

​Fetch Sessions

​EvoAI Features

​Native Evolution API Integration

​Intelligent Conversation Handling

​Multi-Language Support

​Analytics and Insights

​Use Cases

​Best Practices

​Troubleshooting

​Advanced Configuration

​Multiple Agents

​Fallback Configuration

​Integration with Evolution API Features

​Webhook Events

​Multi-Instance Support

​Session Persistence

​Performance Optimization

​Response Time

​Scalability

​Monitoring

​Security

​API Key Management

​Data Privacy

​Access Control

​Related Integrations

Build docs developers (and LLMs) love

EvoAI Integration

What is EvoAI?

Enable EvoAI Integration

Configuration Settings

Create Default Settings

Settings Parameters

Create an EvoAI Agent

Request Parameters

Trigger Types

All Messages

Keyword Trigger

Advanced Trigger

Update EvoAI Agent

Delete EvoAI Agent

Fetch EvoAI Agents

Session Management

Change Session Status

Fetch Sessions

EvoAI Features

Native Evolution API Integration

Intelligent Conversation Handling

Multi-Language Support

Analytics and Insights

Use Cases

Best Practices

Troubleshooting

Advanced Configuration

Multiple Agents

Fallback Configuration

Integration with Evolution API Features

Webhook Events

Multi-Instance Support

Session Persistence

Performance Optimization

Response Time

Scalability

Monitoring

Security

API Key Management

Data Privacy

Access Control

Related Integrations