In this topic, you will better understand what the WhatsApp Web JS API can do regarding contacts. To make it easier to understand, we have divided the approach into some essential points:
For WhatsApp Web, every contact is simply a chat! It might sound strange, but that’s how the platform handles contacts. WhatsApp uses the phone number as an identifier for the chat. Therefore, when accessing contact information, the API follows the same logic.
What’s the difference between getChats() and getContacts()?
getChats(): returns only contacts with whom you’ve had an open conversation.getContacts(): returns all contacts with a WhatsApp account, including those in groups you’re part of.The WhatsApp Web JS API has the same limitations as WhatsApp Web, meaning it’s not possible to:
This happens because WhatsApp Web doesn’t have access to your phonebook. Therefore, the API cannot perform these actions either.
The method that returns the contacts might seem confusing because, when using it, you may see a larger number of contacts than those actually in your phonebook.
This happens because the getContacts() method also returns the numbers of participants in groups you're part of.
📌 Practical example:
If you're in a group with 50 people, all of them will be listed in the return of the getContacts() method, even if they are not saved in your phonebook.
This feature can be useful to identify new contacts within groups or filter messages from unknown people.
🚀 Now that you have a better understanding of how contact management works in WhatsApp Web JS, explore the available methods in the API!
This API allows you to add a new contact to the WhatsApp contact list.
Base URL: https://apiwhatsappweb.com/api/add-contact
All requests must be made to this base URL.
To authenticate requests, you must include the API key (apiKey) and the instance ID ID in the header.
{
"apiKey": "Your API key here",
"id": "Your instance ID here"
}The request body should be a JSON object with the following structure:
{
"firstName": "Contact 1",
"lastName": "Surname 1",
"phone": "554499999999"
}
const axios = require("axios");
let data = JSON.stringify({
"firstName": "Contact 1",
"lastName": "Surname 1",
"phone": "554499999999"
});
let config = {
method: 'post',
url: 'https://apiwhatsappweb.com/api/add-contact',
headers: {
'apiKey': 'Bearer Your_ApiKey',
'id': 'Your_Instance_ID_Here',
'Content-Type': 'application/json'
},
data: data
};
axios.request(config)
.then((response) => console.log(response.data))
.catch((error) => console.log(error));
{
"success": true,
"message": "Contact added successfully!",
"contact": {
"firstName": "Contact 1",
"lastName": "Surname 1",
"phone": "554499999999"
}
}{
"error": "Invalid phone number."
}This API allows you to remove a contact from the WhatsApp contact list.
Base URL: https://apiwhatsappweb.com/api/delete-contact
To authenticate requests, you must include the API key (apiKey) and the instance ID Id (identifier) in the header.
{
"apiKey": "Your API key here",
"id": "Your instance ID here"
}The request body should be a JSON object with the following structure:
{
"id": "INSTANCE_ID",
"phone": "554499999999"
}Examples in Node.js, Python, and C:
Attention!
Removing a contact is an irreversible action. Make sure you want to delete this contact before proceeding.
This API allows you to retrieve the profile picture of a contact on WhatsApp.
Base URL: https://apiwhatsappweb.com/api/get-contact-image
All requests must be made to this base URL.
To authenticate requests, you must include the API key (apiKey) and the instance ID Id (identifier) in the header.
{
"apiKey": "Your API key here",
"id": "Your instance ID here"
}The request body should be a JSON object with the following structure:
{
"id": "INSTANCE_ID",
"phone": "554499999999"
}const axios = require("axios");
let data = JSON.stringify({
"id": "INSTANCE_ID",
"phone": "554499999999"
});
let config = {
method: 'post',
url: 'https://apiwhatsappweb.com/api/get-contact-image',
headers: {
'apiKey': 'Bearer Your_ApiKey',
'id': 'Your_Instance_ID_Here',
'Content-Type': 'application/json'
},
data: data
};
axios.request(config)
.then((response) => console.log(response.data))
.catch((error) => console.log(error));
import requests
url = 'https://apiwhatsappweb.com/api/get-contact-image'
headers = {
'apiKey': 'Bearer Your_ApiKey',
'id': 'Your_Instance_ID_Here',
'Content-Type': 'application/json'
}
data = {
"id": "INSTANCE_ID",
"phone": "554499999999"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
This API allows you to block or unblock a contact on WhatsApp.
Base URL: https://apiwhatsappweb.com/api/block-unblock
All requests must be made to this base URL.
To authenticate requests, you must include the API key (apiKey) and the instance ID Id (identifier) in the header.
{
apiKey: Your API key here
id: Your instance ID here
}The request body should be a JSON object with the following structure:
{
"id": "INSTANCE_ID", // ID of the instance connected to WhatsApp
"phone": "554499999999", // Phone number of the contact to be blocked/unblocked
"action": "block" // Action: "block" to block, "unblock" to unblock
}const axios = require("axios"); let data = JSON.stringify({ "id": "INSTANCE_ID", "phone": "554499999999", "action": "block" }); let config = { method: 'post', url: 'https://apiwhatsappweb.com/api/block-unblock', headers: { 'apiKey': 'Bearer Your_ApiKey', 'id': 'Your_Instance_ID_Here', 'Content-Type': 'application/json' }, data: data }; axios.request(config) .then((response) => { console.log(response.data); }) .catch((error) => { console.log(error); });
import requests url = 'https://apiwhatsappweb.com/api/block-unblock' headers = { 'apiKey': 'Bearer Your_ApiKey', 'id': 'Your_Instance_ID_Here', 'Content-Type': 'application/json' } data = { "id": "INSTANCE_ID", "phone": "554499999999", "action": "block" } response = requests.post(url, headers=headers, json=data) print(response.json())
This API allows you to report a contact on WhatsApp.
URL: https://apiwhatsappweb.com/api/report-contact
All requests must be made to this base URL.
To authenticate requests, include the API Key (apiKey) and Instance ID (id) in the header.
{
"apiKey": "Your API key here",
"id": "Your instance ID here"
}
The request body should be a JSON object with the following structure:
{
"id": "INSTANCE_ID",
"phone": "554499999999",
"reason": "spam"
}
const axios = require("axios");
let data = JSON.stringify({
"id": "INSTANCE_ID",
"phone": "554499999999",
"reason": "spam"
});
let config = {
method: 'post',
url: 'https://apiwhatsappweb.com/api/report-contact',
headers: {
'apiKey': 'Bearer Your_ApiKey',
'id': 'Your_Instance_ID_Here',
'Content-Type': 'application/json'
},
data: data
};
axios.request(config)
.then((response) => console.log(response.data))
.catch((error) => console.log(error));
This API allows you to retrieve all contacts associated with a WhatsApp instance.
URL: https://apiwhatsappweb.com/api/contacts
All requests must be made to this base URL.
To authenticate requests, include the API Key (apiKey) and Instance ID (id) in the header.
{
"apiKey": "Your API key here",
"id": "Your instance ID here"
}
The request body should be a JSON object with the following structure:
{
"id": "INSTANCE_ID" // ID of the instance connected to WhatsApp
}
const axios = require("axios");
let data = JSON.stringify({
"id": "INSTANCE_ID"
});
let config = {
method: 'post',
url: 'https://apiwhatsappweb.com/api/contacts',
headers: {
'apiKey': 'Bearer Your_ApiKey',
'id': 'Your_Instance_ID_Here',
'Content-Type': 'application/json'
},
data: data
};
axios.request(config)
.then(response => console.log(response.data))
.catch(error => console.error(error));