Evolution API (evolutionapi/docs-evolution)

Evolution API

https://github.com/evolutionapi/docs-evolution
Admin
Open-source documentation for the Evolution API

Tokens:168
Snippets:3
Trust Score:8
Update:6 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Evolution API Documentation

## Introduction

Evolution API is a comprehensive WhatsApp integration platform that enables developers to programmatically manage WhatsApp instances, send and receive messages, and integrate with popular AI chatbot frameworks. The API provides RESTful endpoints for creating and managing multiple WhatsApp instances, each with independent authentication and configuration. Built to support both the open-source WHATSAPP-BAILEYS and official WHATSAPP-BUSINESS (Cloud API) engines, Evolution API serves as a complete middleware solution for businesses seeking to automate WhatsApp communications at scale.

The platform offers extensive integration capabilities with AI services (OpenAI, Dify, Flowise, EvoAI, n8n, Evolution Bot), customer support platforms (Chatwoot), and message queue systems (RabbitMQ, AWS SQS, WebSocket). With support for all WhatsApp message types including text, media, polls, lists, interactive buttons, and status updates, Evolution API enables developers to build sophisticated chatbots, customer service solutions, and marketing automation systems. The API follows OpenAPI 3.0 specifications and implements API key authentication for secure access to all endpoints. Evolution API is a free, open-source project designed to empower small businesses, entrepreneurs, and developers with limited resources.

## API Reference

### Create WhatsApp Instance

Create a new WhatsApp instance with customized configuration including webhook integration, message handling preferences, and connection settings.

```bash
curl -X POST https://your-server.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "production-bot",
    "token": "custom-instance-token",
    "qrcode": true,
    "number": "5531987654321",
    "integration": "WHATSAPP-BAILEYS",
    "webhook": "https://your-server.com/webhook",
    "webhook_by_events": true,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE",
      "QRCODE_UPDATED"
    ],
    "reject_call": true,
    "msg_call": "I cannot accept calls at this time",
    "groups_ignore": false,
    "always_online": true,
    "read_messages": false,
    "read_status": false,
    "sync_full_history": true
  }'

# Response
{
  "instance": {
    "instanceName": "production-bot",
    "instanceId": "af6c5b7c-ee27-4f94-9ea8-192393746ddd",
    "status": "created"
  },
  "hash": {
    "apikey": "B3844804-481D-47A4-B69C-F14B4206EB56"
  },
  "settings": {
    "reject_call": true,
    "msg_call": "I cannot accept calls at this time",
    "groups_ignore": false,
    "always_online": true,
    "read_messages": false,
    "read_status": false,
    "sync_full_history": true
  },
  "webhook": {
    "url": "https://your-server.com/webhook",
    "webhook_by_events": true,
    "events": ["MESSAGES_UPSERT", "MESSAGES_UPDATE", "CONNECTION_UPDATE", "QRCODE_UPDATED"]
  }
}
```

### Create WhatsApp Business Cloud API Instance

Create an instance using the official WhatsApp Business Cloud API with a permanent access token.

```bash
curl -X POST https://your-server.com/instance/create \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "business-official",
    "token": "EAAGm0PX4ZCpsBA...",
    "number": "1234567890",
    "businessId": "9876543210",
    "qrcode": false,
    "integration": "WHATSAPP-BUSINESS"
  }'

# Response
{
  "instance": {
    "instanceName": "business-official",
    "instanceId": "b8f3c7d2-ff38-5e05-a9fb-203484857eff",
    "status": "created",
    "integration": "WHATSAPP-BUSINESS"
  },
  "hash": {
    "apikey": "C4955915-592E-58B5-C7AD-G25C5317FC67"
  }
}
```

### Send Text Message

Send text messages with optional features including link preview, mentions, quoted replies, and typing presence indicators.

```bash
curl -X POST https://your-server.com/message/sendText/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5531987654321",
    "options": {
      "delay": 1200,
      "presence": "composing",
      "linkPreview": true,
      "quoted": {
        "key": {
          "remoteJid": "5531987654321@s.whatsapp.net",
          "fromMe": false,
          "id": "BAE5F5A632EAE722"
        },
        "message": {
          "conversation": "What is your opening hours?"
        }
      },
      "mentions": {
        "everyOne": false,
        "mentioned": ["5531999999999"]
      }
    },
    "textMessage": {
      "text": "Hello! We are open Monday to Friday, 9am-6pm. @5531999999999 can help you further."
    }
  }'

# Response
{
  "key": {
    "remoteJid": "5531987654321@s.whatsapp.net",
    "fromMe": true,
    "id": "BAE594145F4C59B4"
  },
  "message": {
    "extendedTextMessage": {
      "text": "Hello! We are open Monday to Friday, 9am-6pm. @5531999999999 can help you further.",
      "contextInfo": {
        "mentionedJid": ["5531999999999@s.whatsapp.net"]
      }
    }
  },
  "messageTimestamp": "1717689097",
  "status": "PENDING"
}
```

### Send Media Files

Send images, videos, audio files, or documents with captions using either URL or base64 encoded data.

```bash
# Send image from URL
curl -X POST https://your-server.com/message/sendMedia/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5531987654321",
    "options": {
      "delay": 1200,
      "presence": "composing"
    },
    "mediaMessage": {
      "mediaType": "image",
      "caption": "Check out our new product catalog!",
      "media": "https://example.com/images/catalog-2024.jpg"
    }
  }'

# Send PDF document with base64
curl -X POST https://your-server.com/message/sendMedia/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5531987654321",
    "mediaMessage": {
      "mediaType": "document",
      "fileName": "invoice-2024-001.pdf",
      "caption": "Your invoice for January 2024",
      "media": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291cmNlcyAyIDAgUgovTWVkaWFCb3ggWzAgMCA1OTUuMjggODQxLjg5XQovQ29udGVudHMgNCAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZSAvTGVuZ3RoIDU1Pj4Kc3RyZWFtCnicMzI2UFAwtjQ0UzC0NDFXMDQAIkMDAyMzQwtzQAC3MwcjAHchBgAKZW5kc3RyZWFtCmVuZG9iag=="
    }
  }'

# Response
{
  "key": {
    "remoteJid": "5531987654321@s.whatsapp.net",
    "fromMe": true,
    "id": "BAE5F5A632EAE722"
  },
  "message": {
    "imageMessage": {
      "url": "https://mmg.whatsapp.net/o1/v/t62.7118-2/12345...",
      "mimetype": "image/jpeg",
      "caption": "Check out our new product catalog!",
      "fileLength": "1305757",
      "height": 1080,
      "width": 1920,
      "jpegThumbnail": "/9j/4AAQSkZJRgABAQAAAQ..."
    }
  },
  "messageTimestamp": "1717775575",
  "status": "PENDING"
}
```

### Send Interactive Buttons

Send interactive button messages with up to 3 quick-reply buttons for user interactions.

```bash
curl -X POST https://your-server.com/message/sendButtons/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5531987654321",
    "buttonMessage": {
      "title": "Choose an option",
      "description": "How can we help you today?",
      "footerText": "Support Team",
      "buttons": [
        {
          "type": "replyButton",
          "displayText": "Technical Support",
          "id": "tech_support"
        },
        {
          "type": "replyButton",
          "displayText": "Sales",
          "id": "sales"
        },
        {
          "type": "replyButton",
          "displayText": "Billing",
          "id": "billing"
        }
      ]
    }
  }'

# Response
{
  "key": {
    "remoteJid": "5531987654321@s.whatsapp.net",
    "fromMe": true,
    "id": "BAE5E2B843DCB922"
  },
  "message": {
    "buttonsMessage": {
      "contentText": "How can we help you today?",
      "footerText": "Support Team",
      "buttons": [
        {
          "buttonId": "tech_support",
          "buttonText": {
            "displayText": "Technical Support"
          }
        }
      ]
    }
  },
  "messageTimestamp": "1717776334",
  "status": "PENDING"
}
```

### Send Interactive List

Send interactive list messages with up to 10 options organized in sections for menu-style interactions.

```bash
curl -X POST https://your-server.com/message/sendList/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5531987654321",
    "options": {
      "delay": 1200,
      "presence": "composing"
    },
    "listMessage": {
      "title": "Customer Support Menu",
      "description": "How can we help you today?",
      "buttonText": "View Options",
      "footerText": "Select an option from the list",
      "sections": [
        {
          "title": "Common Questions",
          "rows": [
            {
              "title": "Business Hours",
              "description": "View our opening hours",
              "rowId": "option1"
            },
            {
              "title": "Pricing Information",
              "description": "View our service prices",
              "rowId": "option2"
            }
          ]
        },
        {
          "title": "Support",
          "rows": [
            {
              "title": "Technical Support",
              "description": "Get help with technical issues",
              "rowId": "tech_support"
            },
            {
              "title": "Talk to Agent",
              "description": "Connect with a human agent",
              "rowId": "human_agent"
            }
          ]
        }
      ]
    }
  }'

# Response
{
  "key": {
    "remoteJid": "5531987654321@s.whatsapp.net",
    "fromMe": true,
    "id": "BAE5E2A732CAB811"
  },
  "message": {
    "listMessage": {
      "title": "Customer Support Menu",
      "description": "How can we help you today?",
      "buttonText": "View Options"
    }
  },
  "messageTimestamp": "1717776234",
  "status": "PENDING"
}
```

### Create WhatsApp Group

Create a new WhatsApp group with multiple participants and configure group settings.

```bash
curl -X POST https://your-server.com/group/create/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Product Launch Team 2024",
    "description": "Coordination group for Q2 2024 product launch. All marketing, sales, and product team members.",
    "participants": [
      "5531987654321",
      "5531999999999",
      "5531888888888",
      "5531777777777"
    ]
  }'

# Response
{
  "id": "120363123456789012@g.us",
  "subject": "Product Launch Team 2024",
  "subjectOwner": "5531987654321@s.whatsapp.net",
  "subjectTime": 1717777890,
  "creation": 1717777890,
  "owner": "5531987654321@s.whatsapp.net",
  "desc": "Coordination group for Q2 2024 product launch. All marketing, sales, and product team members.",
  "participants": [
    {
      "id": "5531987654321@s.whatsapp.net",
      "isAdmin": true,
      "isSuperAdmin": true
    },
    {
      "id": "5531999999999@s.whatsapp.net",
      "isAdmin": false,
      "isSuperAdmin": false
    },
    {
      "id": "5531888888888@s.whatsapp.net",
      "isAdmin": false,
      "isSuperAdmin": false
    },
    {
      "id": "5531777777777@s.whatsapp.net",
      "isAdmin": false,
      "isSuperAdmin": false
    }
  ]
}
```

### Configure Webhook Integration

Set up webhook endpoints to receive real-time events from WhatsApp with selective event filtering.

```bash
curl -X POST https://your-server.com/webhook/set/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/whatsapp",
    "webhook_by_events": true,
    "webhook_base64": true,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "MESSAGES_DELETE",
      "SEND_MESSAGE",
      "CONNECTION_UPDATE",
      "QRCODE_UPDATED",
      "GROUPS_UPSERT",
      "GROUP_UPDATE",
      "GROUP_PARTICIPANTS_UPDATE",
      "CHATS_UPDATE",
      "CONTACTS_UPSERT",
      "PRESENCE_UPDATE",
      "CALL"
    ]
  }'

# Response
{
  "url": "https://your-server.com/webhooks/whatsapp",
  "webhook_by_events": true,
  "webhook_base64": true,
  "events": [
    "MESSAGES_UPSERT",
    "MESSAGES_UPDATE",
    "MESSAGES_DELETE",
    "SEND_MESSAGE",
    "CONNECTION_UPDATE",
    "QRCODE_UPDATED",
    "GROUPS_UPSERT",
    "GROUP_UPDATE",
    "GROUP_PARTICIPANTS_UPDATE",
    "CHATS_UPDATE",
    "CONTACTS_UPSERT",
    "PRESENCE_UPDATE",
    "CALL"
  ]
}

# Example webhook payload received
{
  "event": "MESSAGES_UPSERT",
  "instance": "production-bot",
  "data": {
    "key": {
      "remoteJid": "5531987654321@s.whatsapp.net",
      "fromMe": false,
      "id": "BAE5F5A632EAE722"
    },
    "pushName": "John Doe",
    "message": {
      "conversation": "Hello, I need help with my order"
    },
    "messageType": "conversation",
    "messageTimestamp": 1717778901,
    "instanceId": "af6c5b7c-ee27-4f94-9ea8-192393746ddd",
    "source": "ios"
  },
  "server_url": "https://your-server.com",
  "apikey": "B3844804-481D-47A4-B69C-F14B4206EB56"
}
```

### Integrate OpenAI ChatGPT Bot

Configure an OpenAI-powered chatbot with custom system prompts, trigger conditions, and conversation management.

```bash
curl -X POST https://your-server.com/openai/create/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "openaiCredsId": "creds-openai-123",
    "botType": "assistant",
    "assistantId": "asst_abc123xyz789",
    "model": "gpt-4o",
    "systemMessages": [
      "You are a helpful customer service assistant for an e-commerce company.",
      "Always be polite, professional, and concise.",
      "If you cannot help with a request, offer to connect the customer with a human agent.",
      "Never share customer data or internal company information."
    ],
    "maxTokens": 2000,
    "temperature": 0.7,
    "topP": 1.0,
    "triggerType": "keyword",
    "triggerOperator": "contains",
    "triggerValue": "help,support,question,assist",
    "expire": 3600,
    "keywordFinish": "#exit",
    "delayMessage": 1000,
    "unknownMessage": "I did not understand your message. Could you please rephrase?",
    "listeningFromMe": false,
    "keepOpen": false
  }'

# Response
{
  "id": "bot-openai-production-123",
  "enabled": true,
  "botType": "assistant",
  "assistantId": "asst_abc123xyz789",
  "model": "gpt-4o",
  "settings": {
    "maxTokens": 2000,
    "temperature": 0.7,
    "topP": 1.0,
    "systemMessages": [
      "You are a helpful customer service assistant for an e-commerce company.",
      "Always be polite, professional, and concise.",
      "If you cannot help with a request, offer to connect the customer with a human agent.",
      "Never share customer data or internal company information."
    ]
  },
  "trigger": {
    "triggerType": "keyword",
    "triggerOperator": "contains",
    "triggerValue": "help,support,question,assist"
  },
  "session": {
    "expire": 3600,
    "keywordFinish": "#exit",
    "keepOpen": false
  },
  "instance": "production-bot",
  "createdAt": "2024-06-07T15:30:00.000Z"
}
```

### Configure EvoAI Bot Integration

Connect EvoAI, Evolution API's own AI technology, for advanced chatbot automation and intelligent interactions.

```bash
curl -X POST https://your-server.com/evoai/create/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "agentUrl": "https://evoai.site.com/v1",
    "apiKey": "app-123456",
    "triggerType": "keyword",
    "triggerOperator": "contains",
    "triggerValue": "help,support,info",
    "expire": 20,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "Message not recognized",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 0,
    "ignoreJids": []
  }'

# Response
{
  "id": "bot-evoai-production-456",
  "enabled": true,
  "agentUrl": "https://evoai.site.com/v1",
  "trigger": {
    "triggerType": "keyword",
    "triggerOperator": "contains",
    "triggerValue": "help,support,info"
  },
  "session": {
    "expire": 20,
    "keywordFinish": "#EXIT",
    "keepOpen": false
  },
  "instance": "production-bot",
  "createdAt": "2024-06-07T15:45:00.000Z"
}

# Manage EvoAI session status
curl -X POST https://your-server.com/evoai/changeStatus/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "5531987654321@s.whatsapp.net",
    "status": "closed"
  }'
```

### Configure Evolution Bot Integration

Set up Evolution Bot, a universal chatbot integration that works with any custom API endpoint.

```bash
curl -X POST https://your-server.com/evolutionBot/create/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "apiUrl": "https://api.mycompany.com/chatbot",
    "apiKey": "custom-api-key-123",
    "triggerType": "all",
    "triggerOperator": "none",
    "expire": 30,
    "keywordFinish": "#EXIT",
    "delayMessage": 1000,
    "unknownMessage": "I did not understand your message.",
    "listeningFromMe": false,
    "stopBotFromMe": false,
    "keepOpen": false,
    "debounceTime": 5,
    "ignoreJids": []
  }'

# Response
{
  "id": "bot-evolution-production-789",
  "enabled": true,
  "apiUrl": "https://api.mycompany.com/chatbot",
  "trigger": {
    "triggerType": "all",
    "triggerOperator": "none"
  },
  "session": {
    "expire": 30,
    "keywordFinish": "#EXIT",
    "keepOpen": false
  },
  "instance": "production-bot",
  "createdAt": "2024-06-07T16:00:00.000Z"
}

# Your API should respond with this format
{
  "message": "Your response message here"
}
```

### Configure Typebot Integration

Connect a Typebot conversational flow for visual chatbot building with no-code automation.

```bash
curl -X POST https://your-server.com/typebot/set/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://typebot.io",
    "typebot": "customer-onboarding-flow-v2",
    "expire": 3600,
    "keyword_finish": "#finish",
    "delay_message": 1000,
    "unknown_message": "Sorry, I did not understand. Please choose from the options provided.",
    "listening_from_me": false,
    "triggerType": "keyword",
    "triggerOperator": "startsWith",
    "triggerValue": "start,begin,hi,hello"
  }'

# Response
{
  "enabled": true,
  "url": "https://typebot.io",
  "typebot": "customer-onboarding-flow-v2",
  "expire": 3600,
  "keyword_finish": "#finish",
  "delay_message": 1000,
  "unknown_message": "Sorry, I did not understand. Please choose from the options provided.",
  "listening_from_me": false,
  "trigger": {
    "triggerType": "keyword",
    "triggerOperator": "startsWith",
    "triggerValue": "start,begin,hi,hello"
  }
}

# Start a Typebot session manually
curl -X POST https://your-server.com/typebot/start/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "5531987654321@s.whatsapp.net",
    "startSession": true,
    "variables": [
      {
        "name": "customer_name",
        "value": "John Doe"
      },
      {
        "name": "customer_email",
        "value": "john@example.com"
      }
    ]
  }'
```

### Search and Retrieve Messages

Query message history with flexible filtering criteria including phone numbers, message IDs, and timestamps.

```bash
curl -X POST https://your-server.com/chat/findMessages/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "key": {
        "remoteJid": "5531987654321@s.whatsapp.net"
      }
    },
    "limit": 50
  }'

# Search messages by content
curl -X POST https://your-server.com/chat/findMessages/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "key": {
        "remoteJid": "5531987654321@s.whatsapp.net"
      },
      "message": {
        "conversation": {
          "contains": "order"
        }
      }
    }
  }'

# Response
[
  {
    "key": {
      "remoteJid": "5531987654321@s.whatsapp.net",
      "fromMe": false,
      "id": "BAE5F5A632EAE722"
    },
    "pushName": "John Doe",
    "message": {
      "conversation": "Hello, I need help with my order #12345"
    },
    "messageType": "conversation",
    "messageTimestamp": 1717778901,
    "owner": "production-bot",
    "source": "ios"
  },
  {
    "key": {
      "remoteJid": "5531987654321@s.whatsapp.net",
      "fromMe": true,
      "id": "BAE594145F4C59B4"
    },
    "message": {
      "extendedTextMessage": {
        "text": "I can help you with your order. Let me check the status."
      }
    },
    "messageType": "extendedTextMessage",
    "messageTimestamp": 1717778935,
    "owner": "production-bot"
  }
]
```

### Chat Controller Operations

Mark messages as read/unread, archive chats, block/unblock contacts, and manage chat operations.

```bash
# Mark message as read
curl -X POST https://your-server.com/chat/markMessageAsRead/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "5531987654321@s.whatsapp.net",
    "id": "BAE5F5A632EAE722",
    "fromMe": false
  }'

# Mark message as unread
curl -X POST https://your-server.com/chat/markMessageAsUnread/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "5531987654321@s.whatsapp.net"
  }'

# Block contact
curl -X POST https://your-server.com/chat/updateBlockStatus/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "5531987654321@s.whatsapp.net",
    "status": "block"
  }'

# Unblock contact
curl -X POST https://your-server.com/chat/updateBlockStatus/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remoteJid": "5531987654321@s.whatsapp.net",
    "status": "unblock"
  }'

# Get media in base64 format
curl -X POST https://your-server.com/chat/getBase64FromMediaMessage/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": {
      "remoteJid": "5531987654321@s.whatsapp.net",
      "id": "BAE5F5A632EAE722",
      "fromMe": false
    },
    "message": {
      "imageMessage": {
        "url": "https://mmg.whatsapp.net/..."
      }
    }
  }'

# Response
{
  "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ..."
}
```

### Configure RabbitMQ Event Integration

Set up RabbitMQ integration to stream WhatsApp events to a message queue for distributed processing.

```bash
curl -X POST https://your-server.com/rabbitmq/set/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE",
      "SEND_MESSAGE"
    ]
  }'

# Response
{
  "enabled": true,
  "events": [
    "MESSAGES_UPSERT",
    "MESSAGES_UPDATE",
    "CONNECTION_UPDATE",
    "SEND_MESSAGE"
  ]
}

# Configure AWS SQS instead
curl -X POST https://your-server.com/sqs/set/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "events": [
      "MESSAGES_UPSERT",
      "CONNECTION_UPDATE"
    ]
  }'

# Configure WebSocket for real-time streaming
curl -X POST https://your-server.com/websocket/set/production-bot \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "events": [
      "MESSAGES_UPSERT",
      "CONNECTION_UPDATE",
      "QRCODE_UPDATED"
    ]
  }'
```

### Manage Instance Connection State

Check connection status, connect to WhatsApp, restart instances, or logout to disconnect.

```bash
# Check connection state
curl -X GET https://your-server.com/instance/connectionState/production-bot \
  -H "apikey: YOUR_API_KEY"

# Response
{
  "instance": {
    "instanceName": "production-bot",
    "status": "open"
  },
  "state": "open",
  "statusReason": 200
}

# Connect instance (generates QR code)
curl -X GET https://your-server.com/instance/connect/production-bot \
  -H "apikey: YOUR_API_KEY"

# Response
{
  "code": "2@abc123xyz789...",
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}

# Restart instance
curl -X PUT https://your-server.com/instance/restart/production-bot \
  -H "apikey: YOUR_API_KEY"

# Logout instance
curl -X DELETE https://your-server.com/instance/logout/production-bot \
  -H "apikey: YOUR_API_KEY"

# Response
{
  "status": "success",
  "message": "Instance logged out successfully"
}
```

### Fetch All Instances

List all WhatsApp instances with their configuration, connection status, and integration settings.

```bash
curl -X GET https://your-server.com/instance/fetchInstances \
  -H "apikey: YOUR_API_KEY"

# Filter by instance name
curl -X GET "https://your-server.com/instance/fetchInstances?instanceName=production-bot" \
  -H "apikey: YOUR_API_KEY"

# Response
[
  {
    "instance": {
      "instanceName": "production-bot",
      "instanceId": "af6c5b7c-ee27-4f94-9ea8-192393746ddd",
      "owner": "5531987654321@s.whatsapp.net",
      "profileName": "Customer Support Bot",
      "profilePictureUrl": "https://pps.whatsapp.net/v/...",
      "profileStatus": "Available 24/7",
      "status": "open",
      "serverUrl": "https://evolution-api.example.com",
      "apikey": "B3844804-481D-47A4-B69C-F14B4206EB56",
      "integration": {
        "integration": "WHATSAPP-BAILEYS"
      }
    }
  },
  {
    "instance": {
      "instanceName": "test-instance",
      "instanceId": "421a4121-a3d9-40cc-a8db-c3a1df353126",
      "status": "close",
      "serverUrl": "https://evolution-api.example.com",
      "apikey": "123456-ABCDEF-789012"
    }
  }
]
```

## Summary

Evolution API serves as a comprehensive middleware solution for WhatsApp Business integration, enabling enterprises to automate customer communications, build intelligent chatbots, and manage multiple WhatsApp accounts from a single platform. The primary use cases include customer support automation through integration with platforms like Chatwoot and AI services, marketing campaign management through bulk messaging and interactive templates, sales funnel automation using Typebot, OpenAI, EvoAI, Evolution Bot, and n8n conversational flows, and notification systems for transactional alerts and updates. Organizations leverage Evolution API to reduce response times, handle higher message volumes, and provide 24/7 automated support while maintaining the ability to escalate to human agents when needed. With support for both the open-source Baileys library and official WhatsApp Business Cloud API, developers can choose the integration method that best fits their needs and compliance requirements.

The platform's extensive integration ecosystem makes it suitable for diverse implementation patterns including serverless architectures using AWS SQS, microservices with RabbitMQ message queues, real-time applications via WebSocket streaming, and traditional webhook-based integrations. Developers can build sophisticated multi-instance deployments where each WhatsApp number operates independently with its own configuration, webhooks, and AI bot integrations. The API's support for all WhatsApp message types—from simple text to interactive lists, polls, buttons, and status updates—combined with comprehensive group management, profile customization capabilities, and advanced chat operations (blocking, marking as read/unread, archiving), provides the flexibility needed for both simple notification systems and complex conversational AI applications. With proper authentication, event filtering, and webhook configuration, Evolution API enables scalable, production-ready WhatsApp integrations that handle millions of messages while maintaining reliability and performance. As a free and open-source project, Evolution API democratizes access to powerful WhatsApp automation capabilities for small businesses, developers, and entrepreneurs worldwide.