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:

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

• "phonebook": 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). The response also still includes the older "saved" field with the same true/false value — phonebook and saved are two names for the same flag, just with a clearer name. Both fields are returned together for now; saved is kept only for backward compatibility and will eventually be removed, so use phonebook in new integrations.

Note: WhatsApp does not always provide contact names. Some contacts may appear without a name field in the response — this is expected behavior on WhatsApp's side and cannot be controlled via the API.

Both "saved": true and "saved": false contacts can be deleted via the API. Only "saved": true contacts (those in your phone's address book) can be edited.

When you delete a contact via the API, it disappears from GET /contacts responses entirely — it does not remain with either "saved": true or "saved": false.

Endpoint

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

Example response

{
  "contacts": [
    {
      "id": "601111311480",
      "pushname": "MC",
      "phonebook": false,
      "saved": false
    },
    {
      "id": "972523637999",
      "pushname": "Omer-Ben",
      "phonebook": false,
      "saved": false
    },
    {
      "id": "619528001122",
      "name": "24name",
      "phonebook": true,
      "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.