Skip to content
NexisChat Docs

Chats and Contacts

Chats and Contacts

Section titled “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.

Contact Management

Section titled “Contact Management”

Check WhatsApp Numbers

Section titled “Check WhatsApp Numbers”

Verify if phone numbers are registered on WhatsApp.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/whatsappNumbers

Request Body

Section titled “Request Body”
{
  "numbers": ["5511999999999", "5511888888888", "5511777777777"]
}

cURL Example

Section titled “cURL Example”
Terminal window
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

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

Fetch Contacts

Section titled “Fetch Contacts”

Retrieve contacts from the instance with optional filtering.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/findContacts

Request Body

Section titled “Request Body”
{
  "where": {}
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “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

Section titled “Chat Management”

Fetch Chats

Section titled “Fetch Chats”

Retrieve all chats (conversations) with optional filtering.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/findChats

Request Body

Section titled “Request Body”
{
  "where": {}
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “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

Section titled “Archive/Unarchive Chats”

Archive or unarchive chat conversations.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/archiveChat

Request Body

Section titled “Request Body”
{
  "chat": "5511999999999@s.whatsapp.net",
  "archive": true
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Mute/Unmute Chats”

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

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/muteChat

Request Body

Section titled “Request Body”
{
  "chat": "5511999999999@s.whatsapp.net",
  "muteExpiration": 86400
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Pin/Unpin Chats”

Pin important conversations to the top or unpin them.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/pinChat

Request Body

Section titled “Request Body”
{
  "chat": "5511999999999@s.whatsapp.net",
  "pinned": true
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Mark Chats as Read/Unread”

Update the read status of chats.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/markRead

Request Body

Section titled “Request Body”
{
  "chat": "5511999999999@s.whatsapp.net",
  "read": true
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Message State Management”

Get Message Status

Section titled “Get Message Status”

Retrieve the delivery/read status of a specific message.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/messageStatus

Request Body

Section titled “Request Body”
{
  "key": {
    "id": "message_id_here",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false
  }
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Get Message Delivery Status”

Retrieve delivery status for a message in a specific chat.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/messageDeliveryStatus

Request Body

Section titled “Request Body”
{
  "remoteJid": "5511999999999@s.whatsapp.net",
  "fromMe": true,
  "id": "message_id_here"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Profile and Presence”

Update Profile Status (About)

Section titled “Update Profile Status (About)”

Change the profile “About” status message.

Endpoint

Section titled “Endpoint”
POST /profile/{instanceName}/updateStatus

Request Body

Section titled “Request Body”
{
  "status": "Available for chat"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Update Profile Picture”

Change the account’s profile picture.

Endpoint

Section titled “Endpoint”
POST /profile/{instanceName}/updateProfilePicture

Request Body

Section titled “Request Body”
{
  "image": "https://example.com/new-profile-picture.jpg"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Update Display Name”

Change the account’s display name.

Endpoint

Section titled “Endpoint”
POST /profile/{instanceName}/updateDisplayName

Request Body

Section titled “Request Body”
{
  "name": "New Display Name"
}

cURL Example

Section titled “cURL Example”
Terminal window
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)

Section titled “Presence (Online/Typing)”

Control typing indicators and online presence.

Endpoint

Section titled “Endpoint”
POST /chat/{instanceName}/presence

Request Body

Section titled “Request Body”
{
  "id": "5511999999999@s.whatsapp.net",
  "type": "typing"
}

cURL Example

Section titled “cURL Example”
Terminal window
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

Section titled “Error Handling”

Common Errors

Section titled “Common Errors”
  • Invalid JID format
  • Instance not connected
  • Permission denied for group operations
  • Invalid media/base64 encoding
  • Rate limit exceeded

Standard Error Response

Section titled “Standard Error Response”
{
  "error": true,
  "message": "Error description",
  "details": {
    "code": "VALIDATION_ERROR",
    "field": "id"
  }
}

Best Practices

Section titled “Best Practices”

  1. Validate JIDs

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

  2. Use Efficient Filters

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

  3. Respect Privacy Settings

    Be mindful of user privacy and avoid intrusive presence updates.

  4. Monitor Message States

    Track message delivery and read status for reliable communication flows.

  5. Webhooks Integration

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

Next Steps

Section titled “Next Steps”