Skip to main content

Contacts

Introduction to WhatsApp Contacts​

WhatsApp maintains a local contacts database that is synchronized with the server. When your WhatsApp client connects, it automatically downloads the contacts list to access their public keys, which are essential for end-to-end encryption of messages. This local contacts database is kept up-to-date through real-time events - whenever a contact's information changes (like their profile picture, name, or status), WhatsApp sends an event to update our local database.

Key Features​

  • Local Contacts Database: Access to all your WhatsApp contacts
  • Real-time Updates: Automatic synchronization of contact changes
  • Contact Information: Access to names, profile pictures, and status
  • Encryption Support: Public keys for secure messaging

Available Endpoints​

1. Get Single Contact​

Retrieve information about a specific contact using their phone number.

Endpoint: GET /getcontact?phone=<phone_number>

Example request:

curl "http://localhost:8888/getcontact?phone=1234567890"

Example response:

{
  "jid": "[email protected]",
  "push_name": "John Doe",
  "full_name": "John Doe",
  "first_name": "John"
}

2. Get All Contacts​

Retrieve information about all contacts in your WhatsApp account.

Endpoint: GET /getcontacts

Example request:

curl "http://localhost:8888/getcontacts"

Example response:

[
  {
    "jid": "[email protected]",
    "push_name": "John Doe",
    "full_name": "John Doe",
    "first_name": "John"
  },
  {
    "jid": "[email protected]",
    "push_name": "Jane Smith",
    "full_name": "Jane Smith",
    "first_name": "Jane"
  }
]

Response Fields​

Both endpoints return the following fields for each contact:

  • jid: The contact's WhatsApp ID (phone number with @s.whatsapp.net)
  • push_name: The name shown in WhatsApp (if available)
  • full_name: The contact's full name (if available)
  • first_name: The contact's first name (if available)

Best Practices​

  1. Phone Number Format
    • Include country code without '+' or spaces
    • The server will automatically append "@s.whatsapp.net"
    • Example: "1234567890" for a US number