> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# EvoAI Integration

> Connect EvoAI platform to WhatsApp through Evolution API for advanced AI-powered automation

# 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:

```bash theme={null}
# Enable EvoAI integration
EVOAI_ENABLED=true
```

## Configuration Settings

### Create Default Settings

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

<CodeGroup>
  ```bash cURL theme={null}
  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": ""
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://your-api.com/evoai/settings/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      expire: 300,
      keywordFinish: '#EXIT',
      delayMessage: 1000,
      unknownMessage: 'I did not understand your message.',
      listeningFromMe: false,
      stopBotFromMe: false,
      keepOpen: false,
      debounceTime: 10,
      ignoreJids: [],
      evoaiIdFallback: ''
    })
  });
  ```
</CodeGroup>

#### Settings Parameters

<ResponseField name="expire" type="number" required>
  Session expiration time in seconds. Default: 300 (5 minutes)
</ResponseField>

<ResponseField name="keywordFinish" type="string" required>
  Keyword to terminate the bot session. Example: "#EXIT", "bye"
</ResponseField>

<ResponseField name="delayMessage" type="number" required>
  Delay in milliseconds between messages. Default: 1000
</ResponseField>

<ResponseField name="unknownMessage" type="string" required>
  Message sent when agent encounters an error or cannot respond
</ResponseField>

<ResponseField name="listeningFromMe" type="boolean" required>
  Whether agent responds to messages sent by the instance owner
</ResponseField>

<ResponseField name="stopBotFromMe" type="boolean" required>
  Whether instance owner can stop the agent session
</ResponseField>

<ResponseField name="keepOpen" type="boolean" required>
  Keep session open after completion. Default: false
</ResponseField>

<ResponseField name="debounceTime" type="number" required>
  Seconds to wait before processing rapid messages. Default: 10
</ResponseField>

<ResponseField name="ignoreJids" type="array" required>
  List of JIDs (phone numbers) to ignore
</ResponseField>

<ResponseField name="evoaiIdFallback" type="string">
  Fallback EvoAI agent ID to use when primary agent fails
</ResponseField>

## Create an EvoAI Agent

<Steps>
  <Step title="Get EvoAI credentials">
    Obtain your EvoAI agent URL and API key from the EvoAI platform.
  </Step>

  <Step title="Create agent in Evolution API">
    Register the EvoAI agent with Evolution API using the endpoint below.
  </Step>

  <Step title="Test the integration">
    Send a message matching your trigger to start an EvoAI conversation.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  const evoaiAgent = await fetch('https://your-api.com/evoai/create/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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
    })
  });
  ```
</CodeGroup>

### Request Parameters

<ResponseField name="enabled" type="boolean" required>
  Enable or disable this agent
</ResponseField>

<ResponseField name="description" type="string" required>
  Description of the agent purpose
</ResponseField>

<ResponseField name="agentUrl" type="string" required>
  EvoAI agent endpoint URL
</ResponseField>

<ResponseField name="apiKey" type="string" required>
  Your EvoAI API key for authentication
</ResponseField>

<ResponseField name="triggerType" type="string" required>
  Trigger type: "all", "keyword", or "advanced"
</ResponseField>

<ResponseField name="triggerOperator" type="string">
  For keyword triggers: "equals", "contains", "startsWith", "endsWith", "regex"
</ResponseField>

<ResponseField name="triggerValue" type="string">
  The keyword or regex pattern to trigger this agent
</ResponseField>

## Trigger Types

### All Messages

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

```json theme={null}
{
  "triggerType": "all"
}
```

### Keyword Trigger

Trigger based on specific keywords:

```json theme={null}
{
  "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:

```json theme={null}
{
  "triggerType": "advanced",
  "triggerValue": "^(help|support|assist)\\s"
}
```

## Update EvoAI Agent

Modify an existing EvoAI agent configuration:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://your-api.com/evoai/update/{instance}/{botId}', {
    method: 'PUT',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      enabled: true,
      description: 'Updated Service Agent',
      triggerValue: 'help'
    })
  });
  ```
</CodeGroup>

## Delete EvoAI Agent

Remove an EvoAI agent from your instance:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://your-api.com/evoai/delete/{instance}/{botId} \
    -H "apikey: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://your-api.com/evoai/delete/{instance}/{botId}', {
    method: 'DELETE',
    headers: {
      'apikey': 'your-api-key'
    }
  });
  ```
</CodeGroup>

## Fetch EvoAI Agents

Retrieve all EvoAI agents configured for your instance:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-api.com/evoai/fetch/{instance} \
    -H "apikey: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const agents = await fetch('https://your-api.com/evoai/fetch/{instance}', {
    headers: {
      'apikey': 'your-api-key'
    }
  }).then(res => res.json());
  ```
</CodeGroup>

## Session Management

### Change Session Status

Update the status of an active EvoAI session:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-api.com/evoai/changeStatus/{instance} \
    -H "apikey: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "remoteJid": "5511999999999@s.whatsapp.net",
      "status": "closed"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://your-api.com/evoai/changeStatus/{instance}', {
    method: 'POST',
    headers: {
      'apikey': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      remoteJid: '5511999999999@s.whatsapp.net',
      status: 'closed'
    })
  });
  ```
</CodeGroup>

### Fetch Sessions

Get all active EvoAI sessions:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://your-api.com/evoai/fetchSessions/{instance} \
    -H "apikey: your-api-key"
  ```

  ```javascript JavaScript theme={null}
  const sessions = await fetch('https://your-api.com/evoai/fetchSessions/{instance}', {
    headers: {
      'apikey': 'your-api-key'
    }
  }).then(res => res.json());
  ```
</CodeGroup>

## 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

<Accordion title="Intelligent Customer Support">
  Deploy smart support agents:

  * Automated issue resolution
  * Intelligent ticket routing
  * FAQ automation
  * Escalation to human agents
  * Follow-up and feedback collection
</Accordion>

<Accordion title="Sales Automation">
  Enhance sales processes:

  * Lead qualification and scoring
  * Product recommendations
  * Order processing and tracking
  * Upsell and cross-sell automation
  * Customer journey optimization
</Accordion>

<Accordion title="Appointment Scheduling">
  Automate booking processes:

  * Availability checking
  * Appointment booking and confirmation
  * Reminder notifications
  * Rescheduling and cancellations
  * Calendar integration
</Accordion>

<Accordion title="Information Delivery">
  Provide instant information:

  * Knowledge base queries
  * Product information
  * Service status updates
  * Account information
  * Personalized recommendations
</Accordion>

## Best Practices

<Note>
  EvoAI agents are optimized for WhatsApp's conversational format. Keep responses concise and actionable.
</Note>

<Warning>
  Monitor your agent's performance regularly and update configurations based on user interactions and feedback.
</Warning>

* **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

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

## Advanced Configuration

### Multiple Agents

Deploy specialized agents for different purposes:

```javascript theme={null}
// 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:

```json theme={null}
{
  "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

## Related Integrations

* [OpenAI](/integrations/openai) - OpenAI GPT models
* [Dify](/integrations/dify) - LLM orchestration platform
* [Flowise](/integrations/flowise) - Visual AI workflow builder
* [N8N](/integrations/n8n) - Workflow automation