👤 Contacts

Methods for contacts.

Features#

Here’s the list of features that are available by 🏭 Engines:

API - Contacts#

See the list of engines that support the feature ->.

Get all contacts#

Get your contacts

GET /api/contacts/all?session={NAME}

[
  {
    "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/contacts/all?session={NAME}&limit=100&offset=0&sortBy=id&sortOrder=asc

• limit=100 - limit the number of chats to return
• offset=0 - skip the number of chats from the start
• sortBy={field} - sort by field
  • sortBy=id - sort by contact id
  • sortBy=name - sort by contact name
• sortOrder=desc|asc - sort order
  • desc - 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
}

Update contact#

Update contact on your phone address book (and in WhatsApp):

PUT /api/{session}/contacts/{chatId}

{
  "firstName": "John",
  "lastName": "Doe"
}

Path Parameters:

• {session} - session name - default
• {chatId} - chat ID can end with “@c.us” or can be just a phone number - 12132132130

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 ID
• session - session name
• refresh=True - force refresh the picture. By default, we cache it 24 hours. Do not frequently refresh the picture to avoid rate-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 return
• offset: (optional, default: 0) Pagination offset

Response:

[
  {
    "lid": "123123123@lid",
    "pn": "123456789@c.us"
  }
]

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)

{
  "lid": "123123123@lid",
  "pn": "123456789@c.us"
}

{
  "lid": "123123123@lid",
  "pn": null
}

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)

{
  "lid": "123123123@lid",
  "pn": "123456789@c.us"
}

{
  "lid": null,
  "pn": "123456789@c.us"
}

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.