Skip to main content

Contact Operations

Manage contacts including blocking, unblocking, and retrieving contact information.

Block Contact​

Block a contact on WhatsApp.

POST /sessions/{id}/contacts/block

Headers​

HeaderValue
X-API-KeyYour session API key

Request Body​

ParameterTypeRequiredDescription
jidstringYesContact phone number or JID

Example Request​

curl -X POST http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/contacts/block \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "919988066776"
  }'

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "message": "Contact blocked successfully"
}
info

Blocked contacts cannot send you messages or see your online status.

Unblock Contact​

Unblock a previously blocked contact.

POST /sessions/{id}/contacts/unblock

Headers​

HeaderValue
X-API-KeyYour session API key

Request Body​

ParameterTypeRequiredDescription
jidstringYesContact phone number or JID

Example Request​

curl -X POST http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/contacts/unblock \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jid": "919988066776"
  }'

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "message": "Contact unblocked successfully"
}

Get Contact Profile Picture​

Retrieve a contact's profile picture URL.

GET /sessions/{id}/contacts/{jid}/profile-picture

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
jidstringContact phone number (e.g., 919988066776)

Example Request​

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/contacts/919988066776/profile-picture

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "profilePictureUrl": "https://pps.whatsapp.net/v/t61.24694-24/..."
}

Response (No Picture)​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "profilePictureUrl": null
}
Privacy Settings

If the contact has restricted their profile picture visibility, profilePictureUrl will be null.

Get Contact About​

Retrieve a contact's about/status text.

GET /sessions/{id}/contacts/{jid}/about

Headers​

HeaderValue
X-API-KeyYour session API key

Path Parameters​

ParameterTypeDescription
jidstringContact phone number (e.g., 919988066776)

Example Request​

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/e67a00be-ed45-4356-9488-049cabb9895d/contacts/919988066776/about

Response​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "about": "Hey there! I am using WhatsApp",
  "setAt": 1706443200
}

Response Fields​

FieldTypeDescription
jidstringContact's WhatsApp JID
aboutstringContact's status/about text (null if not set or private)
setAtintegerUnix timestamp when status was last updated (null if not available)

Response (Private Status)​

{
  "success": true,
  "jid": "919988066776@s.whatsapp.net",
  "about": null,
  "setAt": null
}
Privacy Settings

If the contact has restricted their about visibility, both about and setAt will be null.

JID Format​

WhatsApp uses JID (Jabber ID) format for identifying users and groups.

Accepted Formats​

All contact endpoints accept both formats:

FormatExampleDescription
Phone Number919988066776Automatically converted to JID
Full JID919988066776@s.whatsapp.netDirect JID format

JID Types​

TypeFormatExample
Individual{phone}@s.whatsapp.net919988066776@s.whatsapp.net
Group{groupId}@g.us120363123456789@g.us

Error Responses​

Contact Not Found​

{
  "success": false,
  "error": "Contact not found"
}

Solution: Verify the phone number is correct and registered on WhatsApp.

Not Authenticated​

{
  "success": false,
  "error": "Not authenticated"
}

Solution: Ensure your session is in ready state.

Invalid JID Format​

{
  "success": false,
  "error": "Invalid JID format"
}

Solution: Use phone number with country code (e.g., 919988066776) or full JID format.

Code Examples​

JavaScript (Node.js)​

const axios = require('axios');

const API_KEY = 'wask_your_session_key';
const SESSION_ID = 'e67a00be-ed45-4356-9488-049cabb9895d';
const BASE_URL = 'http://localhost:3000';

// Block a contact
async function blockContact(phoneNumber) {
  const response = await axios.post(
    `${BASE_URL}/sessions/${SESSION_ID}/contacts/block`,
    { jid: phoneNumber },
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}

// Get contact profile picture
async function getProfilePicture(phoneNumber) {
  const response = await axios.get(
    `${BASE_URL}/sessions/${SESSION_ID}/contacts/${phoneNumber}/profile-picture`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data.profilePictureUrl;
}

// Get contact about
async function getContactAbout(phoneNumber) {
  const response = await axios.get(
    `${BASE_URL}/sessions/${SESSION_ID}/contacts/${phoneNumber}/about`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data.about;
}

// Usage
blockContact('919988066776');
getProfilePicture('919988066776').then(url => console.log('Picture:', url));
getContactAbout('919988066776').then(about => console.log('About:', about));

Python​

import requests

API_KEY = "wask_your_session_key"
SESSION_ID = "e67a00be-ed45-4356-9488-049cabb9895d"
BASE_URL = "http://localhost:3000"

headers = {"X-API-Key": API_KEY}

# Block contact
def block_contact(phone_number):
    url = f"{BASE_URL}/sessions/{SESSION_ID}/contacts/block"
    response = requests.post(url, json={"jid": phone_number}, headers=headers)
    return response.json()

# Get profile picture
def get_profile_picture(phone_number):
    url = f"{BASE_URL}/sessions/{SESSION_ID}/contacts/{phone_number}/profile-picture"
    response = requests.get(url, headers=headers)
    return response.json()["profilePictureUrl"]

# Get contact about
def get_contact_about(phone_number):
    url = f"{BASE_URL}/sessions/{SESSION_ID}/contacts/{phone_number}/about"
    response = requests.get(url, headers=headers)
    return response.json()["about"]

# Usage
block_contact("919988066776")
print("Picture:", get_profile_picture("919988066776"))
print("About:", get_contact_about("919988066776"))

Use Cases​

Contact Management Dashboard​

async function getContactInfo(phoneNumber) {
  const [picture, about] = await Promise.all([
    getProfilePicture(phoneNumber),
    getContactAbout(phoneNumber)
  ]);
  
  return {
    phoneNumber,
    profilePicture: picture,
    about: about,
    hasProfilePicture: picture !== null,
    hasAbout: about !== null
  };
}

Bulk Block Contacts​

async function blockMultipleContacts(phoneNumbers) {
  const results = await Promise.allSettled(
    phoneNumbers.map(phone => blockContact(phone))
  );
  
  const blocked = results.filter(r => r.status === 'fulfilled').length;
  const failed = results.filter(r => r.status === 'rejected').length;
  
  return { blocked, failed };
}

// Usage
blockMultipleContacts(['919988066776', '919988066777']);

Contact Verification​

async function verifyContact(phoneNumber) {
  try {
    const about = await getContactAbout(phoneNumber);
    return {
      exists: true,
      hasAbout: about !== null,
      phoneNumber
    };
  } catch (error) {
    return {
      exists: false,
      phoneNumber
    };
  }
}

Best Practices​

  1. Check Privacy Settings

    • Not all contacts share their profile picture or about
    • Handle null values gracefully

  2. Rate Limiting

    • Don't make too many requests in quick succession
    • Use batch operations when possible

  3. Error Handling

    • Always handle cases where contact info is unavailable
    • Implement retry logic for network errors

  4. Caching

    • Cache profile pictures and about text
    • Update cache periodically (e.g., daily)

  5. User Experience

    • Show placeholder images when profile picture is null
    • Display default status when about is unavailable