Understanding WhatsApp instances, their lifecycle, and management in Evolution API Lite

WhatsApp Instances

A WhatsApp "instance" in Evolution API Lite represents a single WhatsApp connection that can send and receive messages. Each instance maintains its own authentication session, connection state, and configuration settings.

What is an Instance?

An instance is essentially a virtual WhatsApp client that:

Maintains a persistent connection to WhatsApp servers
Has its own phone number and authentication session
Can send and receive messages independently
Maintains separate contacts, chats, and message history
Has configurable settings and behavior

Think of each instance as a separate WhatsApp account that you can control programmatically through the API.

Instance Lifecycle

1. Creation

Instances are created using the /instance/create endpoint with the global API key:

curl -X POST http://localhost:8080/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_GLOBAL_API_KEY" \
  -d '{
    "instanceName": "my-whatsapp-bot",
    "integration": "WHATSAPP-BAILEYS",
    "qrcode": true
  }'

Response:

{
  "instance": {
    "instanceName": "my-whatsapp-bot",
    "instanceId": "550e8400-e29b-41d4-a716-446655440000",
    "integration": "WHATSAPP-BAILEYS",
    "status": "connecting"
  },
  "hash": "B8E7F2A1-9C3D-4E5F-8A2B-1D3E4F5A6B7C",
  "qrcode": {
    "code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "base64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

2. Connection States

Instances can be in one of several connection states:

State	Description	Actions Available
`connecting`	Attempting to connect to WhatsApp	Wait for QR code scan or connection
`open`	Successfully connected and ready	All messaging operations
`close`	Disconnected from WhatsApp	Reconnect or delete

3. Authentication Process

For Baileys integration (WhatsApp Web):

QR Code Generation: Instance generates a QR code for authentication
QR Code Scan: User scans the QR code with their WhatsApp mobile app
Session Establishment: Instance receives authentication credentials
Connection Open: Instance is ready to send/receive messages

Instance Management Operations

Connect to WhatsApp

Initiate or check the connection status:

curl -X POST http://localhost:8080/instance/connect/my-whatsapp-bot \
  -H "apikey: INSTANCE_TOKEN"

Check Connection State

Get the current connection status:

curl -X GET http://localhost:8080/instance/connectionState/my-whatsapp-bot \
  -H "apikey: INSTANCE_TOKEN"

Response:

{
  "instance": {
    "instanceName": "my-whatsapp-bot",
    "state": "open"
  }
}

Restart Instance

Restart a connected instance (useful for troubleshooting):

curl -X POST http://localhost:8080/instance/restart/my-whatsapp-bot \
  -H "apikey: INSTANCE_TOKEN"

Logout Instance

Logout from WhatsApp (maintains instance but disconnects):

curl -X POST http://localhost:8080/instance/logout/my-whatsapp-bot \
  -H "apikey: INSTANCE_TOKEN"

Delete Instance

Permanently delete an instance and all its data:

curl -X DELETE http://localhost:8080/instance/delete/my-whatsapp-bot \
  -H "apikey: INSTANCE_TOKEN"

Deleting an instance permanently removes all associated data including messages, contacts, and chat history. This action cannot be undone.

Fetching Instance Information

Fetch All Instances

Get information about all instances (requires global API key):

curl -X GET http://localhost:8080/instance/fetchInstances \
  -H "apikey: YOUR_GLOBAL_API_KEY"

Fetch Specific Instance

Get information about a specific instance:

curl -X GET http://localhost:8080/instance/fetchInstances?instanceName=my-whatsapp-bot \
  -H "apikey: INSTANCE_TOKEN"

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-whatsapp-bot",
    "connectionStatus": "open",
    "ownerJid": "5511999999999@s.whatsapp.net",
    "profileName": "My Bot",
    "profilePicUrl": "https://...",
    "number": "5511999999999",
    "integration": "WHATSAPP-BAILEYS",
    "token": "B8E7F2A1-9C3D-4E5F-8A2B-1D3E4F5A6B7C",
    "_count": {
      "Message": 150,
      "Contact": 45,
      "Chat": 12
    }
  }
]

Instance Configuration

Settings

Each instance can have custom settings that control its behavior:

{
  "rejectCall": true,
  "msgCall": "I'm a bot, please send a text message",
  "groupsIgnore": false,
  "alwaysOnline": true,
  "readMessages": true,
  "readStatus": true,
  "syncFullHistory": false
}

Setting	Description	Default
`rejectCall`	Automatically reject incoming calls	`false`
`msgCall`	Message to send when rejecting calls	`""`
`groupsIgnore`	Ignore messages from groups	`false`
`alwaysOnline`	Keep instance always online	`false`
`readMessages`	Automatically mark messages as read	`false`
`readStatus`	Automatically read status updates	`false`
`syncFullHistory`	Sync full message history on connect	`false`

Webhooks

Configure webhooks to receive real-time events:

{
  "webhook": {
    "enabled": true,
    "url": "https://your-server.com/webhook",
    "byEvents": false,
    "base64": true,
    "headers": {
      "Authorization": "Bearer your-token"
    }
  }
}

Proxy Configuration

Configure proxy settings for instances that need to route through specific networks:

{
  "proxyHost": "proxy.example.com",
  "proxyPort": 8080,
  "proxyProtocol": "http",
  "proxyUsername": "username",
  "proxyPassword": "password"
}

Best Practices

Resource Management

Create instances only when needed and delete them when no longer in use to optimize server resources.

Connection Monitoring

Regularly monitor instance connection states, especially in production environments:

# Check all instances status
curl -X GET http://localhost:8080/instance/fetchInstances \
  -H "apikey: YOUR_GLOBAL_API_KEY" \
  | jq '.[] | {name: .name, status: .connectionStatus}'