Complete guide to managing chats, contacts, and profiles through Evolution API Lite

Chats and Contacts

Evolution API Lite provides comprehensive functionality for managing chats, contacts, and user profiles. This guide covers fetching conversations, managing contact information, handling message states, and updating profile settings.

All chat and contact operations require authentication via API key and a valid connected instance.

Contact Management

Check WhatsApp Numbers

Verify if phone numbers are registered on WhatsApp.

Endpoint

POST /chat/{instanceName}/whatsappNumbers

Request Body

{
  "numbers": ["5511999999999", "5511888888888", "5511777777777"]
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/whatsappNumbers" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "numbers": ["5511999999999", "5511888888888"]
  }'

Response

[
  {
    "jid": "5511999999999@s.whatsapp.net",
    "exists": true,
    "number": "5511999999999",
    "name": "John Doe"
  },
  {
    "jid": "5511888888888@s.whatsapp.net",
    "exists": false,
    "number": "5511888888888"
  }
]

Fetch Contacts

Retrieve contacts from the instance with optional filtering.

Endpoint

POST /chat/{instanceName}/findContacts

Request Body

{
  "where": {}
}

{
  "where": {
    "pushName": "John"
  }
}

{
  "where": {
    "id": "5511999999999@s.whatsapp.net"
  }
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/findContacts" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "where": {
      "pushName": "John"
    }
  }'

Response

[
  {
    "_id": "contact_id_123",
    "id": "5511999999999@s.whatsapp.net",
    "pushName": "John Doe",
    "profilePictureUrl": "https://example.com/profile.jpg",
    "isGroup": false,
    "isUser": true,
    "isWAContact": true
  }
]

Chat Management

Fetch Chats

Retrieve all chats (conversations) with optional filtering.

Endpoint

POST /chat/{instanceName}/findChats

Request Body

{
  "where": {}
}

{
  "where": {
    "id": "5511999999999@s.whatsapp.net"
  }
}

{
  "where": {},
  "limit": 50
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/findChats" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "where": {},
    "limit": 20
  }'

Response

[
  {
    "_id": "chat_id_123",
    "id": "5511999999999@s.whatsapp.net",
    "name": "John Doe",
    "isGroup": false,
    "unreadCount": 3,
    "archived": false,
    "pinned": false,
    "muteExpiration": 0,
    "lastMessageTimestamp": 1640995200
  }
]

Archive/Unarchive Chats

Archive or unarchive chat conversations.

Endpoint

POST /chat/{instanceName}/archiveChat

Request Body

{
  "chat": "5511999999999@s.whatsapp.net",
  "archive": true
}

{
  "chat": "5511999999999@s.whatsapp.net",
  "archive": false
}

{
  "lastMessage": {
    "key": {
      "id": "message_id_here",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    },
    "messageTimestamp": 1640995200
  },
  "archive": true
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/archiveChat" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "chat": "5511999999999@s.whatsapp.net",
    "archive": true
  }'

Mute/Unmute Chats

Control chat notifications by muting for a specified duration or unmuting.

Endpoint

POST /chat/{instanceName}/muteChat

Request Body

{
  "chat": "5511999999999@s.whatsapp.net",
  "muteExpiration": 86400
}

{
  "chat": "5511999999999@s.whatsapp.net",
  "muteExpiration": 0
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/muteChat" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "chat": "5511999999999@s.whatsapp.net",
    "muteExpiration": 86400
  }'

Pin/Unpin Chats

Pin important conversations to the top or unpin them.

Endpoint

POST /chat/{instanceName}/pinChat

Request Body

{
  "chat": "5511999999999@s.whatsapp.net",
  "pinned": true
}

{
  "chat": "5511999999999@s.whatsapp.net",
  "pinned": false
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/pinChat" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "chat": "5511999999999@s.whatsapp.net",
    "pinned": true
  }'

Mark Chats as Read/Unread

Update the read status of chats.

Endpoint

POST /chat/{instanceName}/markRead

Request Body

{
  "chat": "5511999999999@s.whatsapp.net",
  "read": true
}

{
  "chat": "5511999999999@s.whatsapp.net",
  "read": false
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/markRead" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "chat": "5511999999999@s.whatsapp.net",
    "read": true
  }'

Message State Management

Get Message Status

Retrieve the delivery/read status of a specific message.

Endpoint

POST /chat/{instanceName}/messageStatus

Request Body

{
  "key": {
    "id": "message_id_here",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  }
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/messageStatus" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "key": {
      "id": "message_id_here",
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false
    }
  }'

Get Message Delivery Status

Retrieve delivery status for a message in a specific chat.

Endpoint

POST /chat/{instanceName}/messageDeliveryStatus

Request Body

{
  "remoteJid": "5511999999999@s.whatsapp.net",
  "fromMe": true,
  "id": "message_id_here"
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/messageDeliveryStatus" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true,
    "id": "message_id_here"
  }'

Profile and Presence

Update Profile Status (About)

Change the profile "About" status message.

Endpoint

POST /profile/{instanceName}/updateStatus

Request Body

{
  "status": "Available for chat"
}

cURL Example

curl -X POST "https://your-api-url/profile/your-instance/updateStatus" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "status": "Available for chat"
  }'

Update Profile Picture

Change the account's profile picture.

Endpoint

POST /profile/{instanceName}/updateProfilePicture

Request Body

{
  "image": "https://example.com/new-profile-picture.jpg"
}

You can provide the image as a URL or as base64 encoded data using the format: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...

cURL Example

curl -X POST "https://your-api-url/profile/your-instance/updateProfilePicture" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "image": "https://example.com/profile.png"
  }'

Update Display Name

Change the account's display name.

Endpoint

POST /profile/{instanceName}/updateDisplayName

Request Body

{
  "name": "New Display Name"
}

cURL Example

curl -X POST "https://your-api-url/profile/your-instance/updateDisplayName" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "name": "Support Account"
  }'

Presence (Online/Typing)

Control typing indicators and online presence.

Endpoint

POST /chat/{instanceName}/presence

Request Body

{
  "id": "5511999999999@s.whatsapp.net",
  "type": "typing"
}

{
  "id": "5511999999999@s.whatsapp.net",
  "type": "recording"
}

{
  "id": "5511999999999@s.whatsapp.net",
  "type": "paused"
}

cURL Example

curl -X POST "https://your-api-url/chat/your-instance/presence" \
  -H "Content-Type: application/json" \
  -H "apikey: your-api-key" \
  -d '{
    "id": "5511999999999@s.whatsapp.net",
    "type": "typing"
  }'

Error Handling

Common Errors

Invalid JID format
Instance not connected
Permission denied for group operations
Invalid media/base64 encoding
Rate limit exceeded

Standard Error Response

{
  "error": true,
  "message": "Error description",
  "details": {
    "code": "VALIDATION_ERROR",
    "field": "id"
  }
}

Best Practices

Use the correct JID format for users (s.whatsapp.net) and groups (g.us).

Apply filters when fetching contacts/chats to reduce payload size and improve performance.

Be mindful of user privacy and avoid intrusive presence updates.

Track message delivery and read status for reliable communication flows.

Set up webhooks to receive real-time updates for chats, contacts, and messages.

Next Steps

Learn about Managing Groups
Explore Sending Messages
Set up Event System webhooks for real-time updates

Chats and Contacts

On this page