Skip to content

Conversations

List group members

Returns the members of a group conversation as WhatsApp shows them to group members: WhatsApp id, phone number (when WhatsApp shares it), name and admin flags. Only for numbers connected by QR code. The list is cached for 10 minutes; refresh=1 asks WhatsApp again.

GET/api/conversations/{id}/participants
  • Bearer API key
  • Scope: read or write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Path parameters

  • iduuidrequired

    Conversation id of a group chat on a number connected by QR code.

    Example
    b2d4e6f8-0a1c-4e3a-8b5d-7f9a1c3e5b7d

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Query parameters

  • refreshbooleanoptional

    Send 1 (or true) to ask WhatsApp again instead of using the stored list. Honoured at most once every 30 seconds per group; within that window you get the stored list (check fetched_at).

    Default
    0

Response

200 OKapplication/json

  • groupobject

    The group.

    Show child attributesHide child attributes3
    • jidstring

      Group id (<digits>@g.us).

    • namestring

      Group name from WhatsApp, else the conversation’s saved name.

    • participant_countinteger

      Member count WhatsApp reports, never less than the number of participants. It can be higher when WhatsApp does not list every member (for example in community announcement groups).

  • participantsarray<object>

    Members, admins first, then by name (members without a name last), then by phone.

    Show child attributesHide child attributes5
    • jidstring

      The member’s WhatsApp id: a phone id (<digits>@s.whatsapp.net) or a private id (<digits>@lid) when WhatsApp addresses the member without a number.

      Example
      15550100123@s.whatsapp.net
    • phonestring

      Phone number in E.164 with +, or "" when WhatsApp hides it. Numbers come only from WhatsApp: never guessed.

      Example
      +15550100123
    • namestring

      The name the linked phone knows (address book name, business name, then WhatsApp profile name), else the name of a saved contact in this workspace, else "".

      Example
      Jordan Lee
    • is_adminboolean

      Group admin (super admins included).

    • is_super_adminboolean

      The group’s creator (super admin).

  • fetched_attimestamp

    When WhatsApp was last asked for this list (RFC 3339, UTC).

Status codes

  • 200OK. The group and its members.
  • 400Bad request. invalid conversation id; the conversation is not a group (Group members are only available for group chats); or the workspace uses Cloud API (Meta) numbers (Group members are only available for numbers connected by QR code).
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The X-Tenant-ID header or tenant query does not match the API key’s workspace (API key belongs to a different workspace), or a signed-in user is not a member of the workspace (forbidden).
  • 404Not found. The conversation does not exist in this workspace, belongs to the inactive connection (QR vs Cloud API), or (for agents signed in to the app) is not assigned to you. Also returned when WhatsApp no longer knows the group (WhatsApp could not find this group).
  • 409Conflict. The QR-linked number is not connected (whatsapp is not connected), or it is not a member of the group anymore (The connected WhatsApp number is not a member of this group anymore).
  • 502Bad gateway. WhatsApp did not answer. The failure is remembered for 10 seconds, so retry after that.
  • 500Server error. Something went wrong on our side. Retry with backoff.

Things to know

  • QR numbers only. Members are read from the WhatsApp linked by QR code. Cloud API (Meta) numbers get 400.
  • What WhatsApp shows a member, nothing more. Numbers WhatsApp hides from group members come back as ""; private (@lid) ids are mapped to a number only when WhatsApp has shared it with the linked phone.
  • Cached. WhatsApp is asked only when you call this endpoint (or open the members panel in the inbox), and the answer is kept for 10 minutes per workspace and group. ?refresh=1 asks again, at most once every 30 seconds per group. Lists do not update live when members join or leave.
  • Who can call it. API keys (a read key is enough) and workspace members. Agents signed in to the app only see groups assigned to them; other ids answer 404.
  • Read only. There is no endpoint to message every member of a group.

Ask WhatsApp again

curl "https://whatsappx.si/api/conversations/b2d4e6f8-0a1c-4e3a-8b5d-7f9a1c3e5b7d/participants?refresh=1" \
  -H "Authorization: Bearer $WHATSAPPX_API_KEY"