Skip to Content
Wazend

Contacts

Manage WhatsApp contacts with Wazend: list, get, update, check numbers, block and query LIDs.

Methods to manage WhatsApp contacts. WhatsApp Web doesn't allow adding contacts, so the API doesn't support it either.

@lid and @c.us

WhatsApp assigns a unique LID (Local Identifier) to each user to hide their phone number in groups and other places. You can message anyone using their LID or their PN (phone number, @c.us).

Tip

Use the LIDs API to map between a phone number (@c.us) and a @lid.

Get all contacts

GET /api/contacts/all?session=S0001
Response
[
  {
    "id": "5215551234567@c.us",
    "number": "5215551234567",
    "name": "Juan Pérez",
    "pushname": "Juan",
    "shortName": "Juan",
    "isMe": false,
    "isGroup": false,
    "isWAContact": true,
    "isMyContact": true,
    "isBlocked": false
  }
]

Query parameters:

GET /api/contacts/all?session=S0001&limit=100&offset=0&sortBy=id&sortOrder=asc
  • limit / offset — pagination.
  • sortBy — id or name.
  • sortOrder — desc or asc.

Get contact

GET /api/contacts?contactId=5215551234567&session=S0001

The contactId can be a phone number (5215551234567) or a chat id (5215551234567@c.us or 5215551234567@lid).

Update contact

Update the contact in your phonebook and in WhatsApp:

PUT /api/{session}/contacts/{chatId}
Body
{
  "firstName": "Juan",
  "lastName": "Pérez"
}

Check if the number exists

GET /api/contacts/check-exists?phone=5215551234567&session=S0001
Response
{
  "numberExists": true,
  "chatId": "5215551234567@c.us",
  "pn": "5215551234567@c.us"
}

Brazilian numbers

Use check-exists before sending to a new number to get the correct chatId (due to the digit 9 added after 2012).

Get contact "about"

GET /api/contacts/about?contactId=5215551234567&session=S0001
Response
{ "about": "Hi, I'm using WhatsApp!" }

Get profile picture

GET /api/contacts/profile-picture?contactId=5215551234567&session=S0001&refresh=true
Response
{ "profilePictureURL": "https://ejemplo.com/perfil.jpg" }

Block / unblock contact

POST /api/contacts/block
POST /api/contacts/unblock
Body
{
  "contactId": "5215551234567",
  "session": "S0001"
}

LIDs API

Map a linked identifier (@lid) to a phone number (@c.us) in both directions.

Get all known LIDs

GET /api/{session}/lids?limit=100&offset=0
Response
[
  {
    "lid": "5215551234567@lid",
    "pn": "5215551234567@c.us"
  }
]

Get LIDs count

GET /api/{session}/lids/count
Response
{ "count": 123 }

Get number by LID

GET /api/{session}/lids/{lid}

Remember to escape @ with %40 or use just the number.

Response
{
  "lid": "5215551234567@lid",
  "pn": "5215551234567@c.us"
}

Get LID by phone number

GET /api/{session}/lids/pn/{phoneNumber}
Response
{
  "lid": "5215551234567@lid",
  "pn": "5215551234567@c.us"
}

Lids FAQ

If you can't find a number by LID, you don't have that number in your contacts or you're not a group admin. For groups, try refreshing groups.