👤 Contacts
Methods for contacts.

Features
Here’s the list of features that are available by 🏭 Engines:
👤 Contacts - API
API | WEBJS | NOWEB | GOWS |
---|---|---|---|
Get all contactsGET /api/contacts/all | ✔️ | ✔️*1 | ✔️ |
Get contactGET /api/contacts | ✔️ | ✔️*1 | ✔️ |
Check phone number existsGET /api/contacts/check-exists | ✔️ | ✔️ | ✔️ |
Get “about” contactGET /api/contacts/about | ✔️ | ||
Get profile pictureGET /api/contacts/profile-picture | ✔️ | ✔️ | ✔️ |
Block contactPOST /api/contacts/block | ✔️ | ||
Unblock contactPOST /api/contacts/unblock | ✔️ |
- NOWEB - you need to Enable Store to get chats, contacts and messages
👤 Lids - API
API | WEBJS | NOWEB | GOWS |
---|---|---|---|
Get Known LIDsGET /api/{session}/lids | ✔️ | ✔️*1 | ✔️ |
Get Count of LIDsGET /api/{session}/lids/count | ✔️ | ✔️*1 | ✔️ |
Get Phone Number by LIDGET /api/{session}/lids/{lid} | ✔️ | ✔️*1 | ✔️ |
Get LID by Phone NumberGET /api/{session}/lids/pn/{phoneNumber} | ✔️ | ✔️*1 | ✔️ |
- NOWEB - you need to Enable Store to get chats, contacts and messages
WhatsApp Web does not support adding contacts, so the API doesn’t support it too.
API - Contacts
See the list of engines that support the feature ->.
Get all contacts
Get your contacts
GET /api/{session}/contacts/all
[
{
"id": "11231231231@c.us",
"number": "11231231231",
"name": "Contact Name",
"pushname": "Pushname",
"shortName": "Shortname",
"isMe": true,
"isGroup": false,
"isWAContact": true,
"isMyContact": true,
"isBlocked": false
}
]
Contacts Pagination
If you see timeout or the request takes too long - consider using limit
parameter to get contacts in smaller chunks
GET /api/{session}/contacts/all?limit=100&offset=0&sortBy=id&sortOrder=asc
limit=100
- limit the number of chats to returnoffset=0
- skip the number of chats from the startsortBy={field}
- sort by fieldsortBy=id
- sort by contact idsortBy=name
- sort by contact name
sortOrder=desc|asc
- sort orderdesc
- descending order (A-Z)asc
- ascending order (Z-A)
Get contact
Get contact
GET /api/contacts?contactId={ID}&session={SESSION}
ID
- either phone number (123123123
) or chat id (123123@c.us
)
{
"id": "11231231231@c.us",
"number": "11231231231",
"name": "Contact Name",
"pushname": "Pushname",
"shortName": "Shortname",
"isMe": true,
"isGroup": false,
"isWAContact": true,
"isMyContact": true,
"isBlocked": false
}
Check phone number exists
If you want to check if phone number is registered in WhatsApp (even if the number is not in your contact list) - use this endpoint for that.
GET /api/contacts/check-exists?phone=11231231231&session=default
It returns numberExists
field with true
or false
value and chatId
field with chat ID of the number (if exists).
{
"numberExists": true,
"chatId": "123123123@c.us"
}
Note for 🇧🇷 Brazilian Phone Numbers
You should use the GET /api/contacts/check-exists
endpoint before sending a message to a new phone number
to get the correct chatId because of the additional 9-digit number added after 2012.
Read more about error sending text to half of Brazilian numbers (every number registered before 2012) ->
It’s fine to send the response to chatId
for incoming messages, though - the payload already has the correct chatId
.
Get “about” contact
GET /api/contacts/about?contactId={ID}&session={SESSION}
ID
- either phone number (123123123
) or chat id (123123@c.us
)
{
"about": "Hi, I use WhatsApp!"
}
Get contact profile picture
GET /api/contacts/profile-picture?contactId=11231231231&session=default`
Query:
contactId
- contact IDsession
- session namerefresh=True
- force refresh the picture. By default, we cache it 24 hours. Do not frequently refresh the picture to avoidrate-overlimit
error.
{
"profilePictureURL": "https://example.com/profile.jpg"
}
Block (unblock) contact
Block contact
POST /api/contacts/block
Unblock contact
POST /api/contacts/unblock
{
"contactId": "11231231231",
"session": "default"
}
API - Lids
WhatsApp uses so-called Linked ID (lid
) identifier to hide a user phone number (pn
) from public groups and other places.
The API below you can use to map a linked identifier (@lid
) to a contact phone number (@c.us
).
Get All Known LIDs
GET /api/{session}/lids
Query all known LID-to-phone number mappings for a session.
Query Parameters:
limit
: (optional, default: 100) Number of records to returnoffset
: (optional, default: 0) Pagination offset
Response:
[
{
"lid": "123123123@lid",
"pn": "123456789@c.us"
}
]
Call Get all groups or Refresh groups to populate lid to phone number mapping for all groups.
Get Count of LIDs
GET /api/{session}/lids/count
Returns the number of known LID mappings for a session.
Response:
{
"count": 123
}
Get Phone Number by LID
GET /api/{session}/lids/{lid}
Retrieve the associated phone number for a specific LID.
👉 Remember to escape @
in lid
with %40
(123123%40lid
) or use just a number (123123
)
Get LID by Phone Number
GET /api/{session}/lids/pn/{phoneNumber}
Fetch the LID for a given phone number (chat ID).
👉 Remember to escape @
in phoneNumber
with %40
(123123%40lid
) or use just a number (123123
)
Lids FAQ
- If you don’t find a phone number by lid - you don’t have the phone number in your contact list or you’re not admin in the group.
- For 👥 Groups - try Refresh groups if you don’t find the
lid
but you’re admin in the group.
👉 If nothing helped, and you see phone number for participant on your phone app - please open an issue and tell what 🏭 Engine you’re using and what behaviour you see.