Get contacts

This method is responsible for returning all of your Whatsapp contacts

In WhatsApp, every contact is essentially a chat. So what’s the difference between GET /chats and GET /contacts?

• GET /chats returns only those contacts with whom you have an active or past conversation — in other words, chats that already exist.

• GET /contacts returns all WhatsApp accounts your number can see — including those saved in your phone book and participants of any groups you’re a member of.

This may cause some confusion because GET /contacts usually returns more entries than you actually have saved on your phone. That’s expected: the method includes every user who shares a group with you, even if they are not saved in your address book.

To distinguish real phone contacts from automatically discovered ones, check the saved flag in the response:

• "saved": true — this contact is saved in your phone’s address book.

• "saved": false — this contact is not saved on your phone (e.g., a group participant or there was a private conversation with this number, without adding it to contacts).

Contacts with "saved": false cannot be edited or deleted via the API. Similarly, you cannot create a contact with "saved": true if it already exists in your phone book.

Even if you delete a contact, you may still see it in future responses from GET /contacts, but it will then appear with "saved": false.

Endpoint

GET https://gate.whapi.cloud/contacts

Example response

{
  "contacts": [
    {
      "id": "601111311480",
      "pushname": "MC",
      "saved": false
    },
    {
      "id": "972523637999",
      "pushname": "Omer-Ben",
      "saved": false
    },
    {
      "id": "619528001122",
      "name": "24name",
      "saved": true
    }
  ],
  "count": 100,
  "total": 1317
}

This response includes the list of all visible contacts, the number of returned items (count), and the total number of contacts accessible to your WhatsApp account.