Profiles

Fetch contact or group profile details (status/about, profile picture URL if allowed, names, participants). Supports both user/contact profiles and group profiles. Results are best-effort and respect privacy settings.

Endpoint

Method Path Description
GET /devices/{device_id}/profile Fetch contact or group profile (with query params).
GET /devices/{device_id}/groups List all groups currently joined by the connected device.
  • Headers: Authorization: Bearer <token>
  • Prerequisite: Device must be connected; otherwise you receive a device-not-connected error.
  • Identifier: jid accepts:
    • Contact/User: phone number, phone JID (@s.whatsapp.net), or LID (@lid)
    • Group: group JID (@g.us), e.g., 120363406798553856@g.us
    Treat it as an opaque identifier, not a numeric phone number.
  • Auto-Detection: The endpoint automatically detects whether the JID is a contact or group based on the server suffix (@g.us for groups, @s.whatsapp.net or @lid for contacts).
  • Privacy: WhatsApp may hide status and photo; missing fields are expected when privacy restricts access.

List All Groups

Use this endpoint to discover all group chats the connected device currently participates in.

  • Method: GET /devices/{device_id}/groups
  • Headers: Authorization: Bearer <token>
  • Prerequisite: Device must be connected.
{
  "data": {
    "groups": [
      {
        "jid": "120363406798553856@g.us",
        "name": "My Group Chat",
        "subject": "My Group Chat",
        "description": "Group description or topic",
        "participant_count": 24,
        "is_announce": false,
        "is_locked": false,
        "is_ephemeral": false,
        "is_join_approval_required": false
      }
    ],
    "count": 1
  }
}

Contact vs Group Profiles

This endpoint supports both contact/user profiles and group profiles. The endpoint automatically detects the type based on the JID format:

  • Contact/User: JIDs ending with @s.whatsapp.net or @lid
  • Group: JIDs ending with @g.us

The response includes a type field ("contact" or "group") to indicate which type of profile was returned.

LID vs Phone JID Resolution (Contacts Only)

  • Phone JID: 6281234567890@s.whatsapp.net (derived from a phone number)
  • LID: 1234567890987654321@lid (a privacy identifier; common in webhooks and group contexts)

This endpoint automatically resolves the mapping between LIDs and Phone JIDs whenever WhatsApp provides that information.

  • If you query a LID, the response will include the corresponding phone_jid (if known).
  • If you query a Phone JID, the response will include the corresponding lid (if known).

This is useful for linking "private" LID identities back to known phone numbers for CRM or thread merging.

Request

  • jid — peer identifier:
    • Contact: 15551234567, 15551234567@s.whatsapp.net, or lid_example@lid
    • Group: 120363406798553856@g.us
  • preview (optional, bool) — request thumbnail photo instead of full size.

GET Method (Query Params)

GET /devices/{device_id}/profile?jid=6281234567890&preview=true
GET /devices/{device_id}/profile?jid=120363406798553856@g.us

Response: Contact Profile

When querying a contact/user JID, the response includes:

  • type: "contact"
  • profile.jid: the identifier you queried (normalized).
  • profile.phone_jid: the resolved phone-based identifier (if jid was a LID).
  • profile.lid: the resolved LID-based identifier (if jid was a Phone JID).
  • profile.status: the "About" text.
  • profile.picture_url: link to profile photo (respects privacy).
  • profile.push_name, profile.business_name, profile.verified_name: names as seen by WhatsApp.
  • profile.devices: list of device JIDs for multi-device accounts.
{
  "data": {
    "type": "contact",
    "profile": {
      "jid": "1234567890987654321@lid",
      "phone_jid": "6281234567890@s.whatsapp.net",
      "lid": "1234567890987654321@lid",
      "status": "Available",
      "picture_url": "https://pps.whatsapp.net/...",
      "picture_id": "1059769838",
      "push_name": "John Doe",
      "business_name": "",
      "verified_name": "",
      "devices": [
        "6281234567890@s.whatsapp.net",
        "6281234567890:1@s.whatsapp.net"
      ]
    }
  }
}

If privacy blocks photo access, picture_url and picture_id are empty strings.

Response: Group Profile

When querying a group JID (@g.us), the response includes:

  • type: "group"
  • profile.jid: the group JID.
  • profile.name: the group name.
  • profile.subject: alias for name (same value).
  • profile.description: the group description/topic.
  • profile.picture_url: link to group picture (if available).
  • profile.picture_id: group picture ID (if available, retrieved from picture URL response).
  • profile.participants: array of participant JIDs.
{
  "data": {
    "type": "group",
    "profile": {
      "jid": "120363406798553856@g.us",
      "name": "My Group Chat",
      "subject": "My Group Chat",
      "description": "Group description or topic",
      "picture_url": "https://pps.whatsapp.net/...",
      "picture_id": "abc123",
      "participants": [
        "6281234567890@s.whatsapp.net",
        "6289876543210@s.whatsapp.net",
        "150199452311775@lid"
      ]
    }
  }
}

Group picture may be empty if the group doesn't have a picture set.

Response: Contact Profile (Privacy Blocks Photo)

{
  "data": {
    "type": "contact",
    "profile": {
      "jid": "6281234567890@s.whatsapp.net",
      "lid": "1234567890987654321@lid",
      "status": "Available",
      "push_name": "John Doe"
    }
  }
}

When privacy blocks photo access, picture_url and picture_id may be omitted or empty.

Thread Merging (Do Not Use /profile)

If your system currently stores chat history keyed by raw JID, @lid and @s.whatsapp.net may appear as two separate threads for the same human.

To safely merge, implement an internal contact record with multiple aliases (e.g., lid_jid and phone_jid) and link them only with a reliable signal (e.g., the user replies to a verification token sent to the phone JID). Do not merge solely based on /profile output.

Behavior & Notes

Contact Profiles

  • Privacy: status/photo may be empty or omitted if the contact restricts visibility.
  • Identifiers: do not parse to numeric; handle @lid and @s.whatsapp.net equally.
  • LID is optional; it appears only when WhatsApp provides it for the target and should not be treated as a guaranteed mapping.
  • Images: URLs are direct WhatsApp links; fetch and cache downstream if needed.
  • Best-effort: verified/business names appear only for business accounts with that data.

Group Profiles

  • Group JIDs must end with @g.us to be recognized as groups.
  • You must be a participant of the group to retrieve its profile information.
  • Group picture may be empty if the group doesn't have a picture set.
  • Picture ID is retrieved from the picture URL response and may be empty if no picture is available.
  • Participants list includes all current members of the group.

General

  • The endpoint automatically detects contact vs group based on JID format.
  • Response always includes a type field indicating whether it's "contact" or "group".
  • Device must be connected; otherwise you receive a device-not-connected error.