WhatsApp Instances

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

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

sequenceDiagram
participant API
participant Instance
participant WhatsApp
participant Mobile

API->>Instance: Create Instance
Instance->>WhatsApp: Request QR Code
WhatsApp->>Instance: Return QR Code
Instance->>API: Return QR Code
Mobile->>WhatsApp: Scan QR Code
WhatsApp->>Instance: Send Auth Credentials
Instance->>API: Connection Status: open

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"

Caution

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

Tip

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}'

Error Handling

Implement proper error handling for instance operations:

• Connection failures: Retry connection with exponential backoff
• Authentication errors: Generate new QR code or check credentials
• Rate limiting: Respect WhatsApp’s rate limits to avoid temporary blocks

Security

Tip

Always use instance-specific API keys for messaging operations instead of the global API key.

• Store instance tokens securely
• Rotate tokens periodically
• Monitor for unusual activity
• Use HTTPS for all API calls

Common Issues and Solutions

QR Code Expired

If the QR code expires before scanning:

1. Restart the instance to generate a new QR code
2. Ensure the mobile device has stable internet connection
3. Try using a different browser or clearing cache

Connection Drops

If instances frequently disconnect:

1. Check server internet connection stability
2. Verify WhatsApp account is not logged in elsewhere
3. Consider using proxy configuration if behind firewall
4. Monitor server resources (CPU, memory)

Authentication Failures

If authentication fails repeatedly:

1. Logout and reconnect the instance
2. Clear WhatsApp Web sessions in mobile app
3. Verify the phone number is valid and active
4. Check for account restrictions or bans

Note

Evolution API Lite maintains authentication sessions persistently, so instances should remain connected even after server restarts.