List groups

GEThttps://api.wapito.com/v1/groups

Send a channel token on every request: Authorization: Bearer wpt_YOUR_TOKEN

Last reviewed September 17, 2026

Returns a page of the groups the linked account belongs to, with subject, participant count and the settings currently in force. Use it to reconcile your own records after an operator has created or left groups from the phone directly. Participant lists are not included; fetch them per group when you need them.

Parameters

Name	In	Type	Required	Description	Example
`count`	query	`integer`	Optional	Page size, 1-500. Defaults to 100.1–500 · default 100	`50`
`offset`	query	`integer`	Optional	Items to skip before the first returned item. Use it with `count` to page.min 0 · default 0	`0`

Responses

200

A page of groups.

Fields of the 200 response
Field	Type	Required	Description
`count`	`integer`	Required	Number of items in this page.
`groups`	`array of object`	Required	Page of results.
`created_at`	`string \| null`	Required	ISO 8601 creation timestamp.date-time
`description`	`string \| null`	Required	Group description shown in group info.
`id`	`string`	Required	Group id ending in `@g.us`.
`invite_code`	`string \| null`	Required	Current invite code, when the channel is an admin.
`is_announce`	`boolean`	Required	True when only admins may post.
`is_community_announce`	`boolean`	Required	True when this is a community announcement group.
`is_locked`	`boolean`	Required	True when only admins may edit group info.
`owner`	`string \| null`	Required	Id of the account that created the group.
`participants`	`array of object`	Optional	Every participant, on single-group answers (create, get, update, invite accept and preview). List pages leave it out — read the group to get it.
`id`	`string`	Required	Participant id in `@s.whatsapp.net` form.
`joined_at`	`string \| null`	Required	ISO 8601 timestamp the participant joined, when known.date-time
`lid`	`string \| null`	Required	LID when the participant is addressed by LID.
`name`	`string \| null`	Required	Display name known to the channel.
`phone`	`string \| null`	Required	Phone number in digits.
`role`	`string`	Required	Role inside the group.one of member, admin, superadmin
`participants_count`	`integer`	Required	Number of participants including admins.
`picture`	`string \| null`	Required	Group icon URL.
`settings`	`object`	Required	Group security settings; every field maps to one WhatsApp admin toggle.
`info_admin_only`	`boolean`	Required	Only admins may change subject, description and icon.
`member_add_mode`	`string`	Required	Who may add participants directly.one of admin_add, all_member_add
`membership_approval`	`boolean`	Required	New joiners land in the join-request queue instead of the group.
`messages_admin_only`	`boolean`	Required	Only admins may post (announcement group).
`subject`	`string`	Required	Group name shown in the chat list.
`offset`	`integer`	Required	Offset this page started at.
`total`	`integer \| null`	Required	Total matches when the engine can count them, otherwise `null`.

{
  "count": 1,
  "groups": [
    {
      "created_at": "2026-08-02T09:14:00.000Z",
      "description": "Coordination for the Q3 launch. Keep it on topic.",
      "id": "120363041234567890@g.us",
      "invite_code": "HkQ2ZpL9vRtAeYm1",
      "is_announce": false,
      "is_community_announce": false,
      "is_locked": false,
      "owner": "15557654321@s.whatsapp.net",
      "participants_count": 24,
      "picture": "https://pps.whatsapp.net/v/t61.24694-24/group_n.jpg",
      "settings": {
        "info_admin_only": true,
        "member_add_mode": "admin_add",
        "membership_approval": true,
        "messages_admin_only": false
      },
      "subject": "Acme Launch Team"
    }
  ],
  "offset": 0,
  "total": 12
}

400

The request body or query string is malformed, or the recipient cannot be parsed into a WhatsApp id.

Show 2 example bodies

invalid_recipient — `to` is not a dialable number or valid WhatsApp id

{
  "error": {
    "code": "invalid_recipient",
    "details": {
      "to": "+1555"
    },
    "message": "The recipient is not a valid WhatsApp address.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

invalid_request — schema validation failed

{
  "error": {
    "code": "invalid_request",
    "details": {
      "issues": [
        {
          "message": "Array must contain at least 2 element(s)",
          "path": "body.options"
        }
      ]
    },
    "message": "The request payload failed validation.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

401

The channel token is missing, malformed, revoked or belongs to a deleted channel.

Show 2 example bodies

token_revoked — the token was rotated in the dashboard

{
  "error": {
    "code": "token_revoked",
    "message": "This channel token has been revoked.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

unauthorized — no or unusable Bearer token

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid channel token.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

403

The token is valid but the channel may not perform this action right now.

Show 2 example bodies

channel_locked — billing lapsed or the channel was locked by an operator

{
  "error": {
    "code": "channel_locked",
    "details": {
      "reason": "plan_required"
    },
    "message": "This channel is locked.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

forbidden — the channel does not own the target object

{
  "error": {
    "code": "forbidden",
    "message": "You are not allowed to perform this action.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

409

The channel is in the wrong state for this action, or the account type does not support it.

Show 3 example bodies

business_account_required — labels need WhatsApp Business

{
  "error": {
    "code": "business_account_required",
    "message": "This action requires a WhatsApp Business account.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

channel_not_connected — link the number first

{
  "error": {
    "code": "channel_not_connected",
    "details": {
      "status": "qr"
    },
    "message": "The channel is not connected.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

channel_not_in_qr_state — no QR available while the session boots

{
  "error": {
    "code": "channel_not_in_qr_state",
    "details": {
      "status": "created"
    },
    "message": "The channel is not waiting for a QR scan.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

429

A rate limit, a plan quota or one of the anti-ban guards stopped the request. Every one of these is safe to retry later; read `Retry-After` when present.

Show 5 example bodies

cold_send_limit — too many first messages to new recipients this hour

{
  "error": {
    "code": "cold_send_limit",
    "details": {
      "resets_at": "2026-09-15T09:00:00.000Z",
      "window_cap": 20
    },
    "message": "The hourly limit for messages to new recipients is reached.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

quota_exceeded — plan quota for the day or month

{
  "error": {
    "code": "quota_exceeded",
    "details": {
      "quota": "sent",
      "resets_at": "2026-09-16T00:00:00.000Z",
      "used": 150
    },
    "message": "The plan quota for this resource is exhausted.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

rate_limited — per-minute API rate limit

{
  "error": {
    "code": "rate_limited",
    "details": {
      "retry_after": 12
    },
    "message": "Too many requests.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

send_rate_limited — the send queue did not drain within 20 s

{
  "error": {
    "code": "send_rate_limited",
    "details": {
      "retry_after": 5
    },
    "message": "The send queue for this channel is saturated.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

warmup_limit — the warm-up ladder cap for today

{
  "error": {
    "code": "warmup_limit",
    "details": {
      "cap": 200,
      "day": 2
    },
    "message": "The warm-up limit for this channel is reached.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

500

Something went wrong inside Wapito. Quote `request_id` when reporting it.

Show the example body

internal_error — unexpected failure

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

502

The engine answered with an error Wapito could not translate into a more specific code.

Show the example body

engine_error — unexpected engine failure

{
  "error": {
    "code": "engine_error",
    "details": {
      "engine": "gows",
      "status": 500
    },
    "message": "The WhatsApp engine returned an error.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

503

The engine session is not reachable. Retry with backoff.

Show the example body

engine_unavailable — engine down or restarting

{
  "error": {
    "code": "engine_unavailable",
    "details": {
      "engine": "gows"
    },
    "message": "The WhatsApp engine is unavailable.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

504

The engine did not answer before the upstream timeout.

Show the example body

engine_timeout — no answer within the deadline

{
  "error": {
    "code": "engine_timeout",
    "details": {
      "timeout_ms": 20000
    },
    "message": "The WhatsApp engine did not respond in time.",
    "request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
  }
}

Errors

409channel_not_connectedChannel not connected

Code examples

import requests

url = "https://api.wapito.com/v1/groups"

querystring = {"count":"50","offset":"0"}

headers = {"Authorization": "Bearer wpt_YOUR_TOKEN"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Used in

Other endpoints in this group

Reference

Try it on your own number

Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.

Create a free channel Read the docs

Parameters

Responses

200

400

401

403

409

429

500

502

503

504

Errors

Code examples

Used in

Related

Other endpoints in this group

Reference

Try it on your own number