> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lazyapp.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Group chats

> Run small WhatsApp groups from your business number: create, invite, approve, chat, pin and delete.

A WhatsApp **group** here is a real group chat your business number runs: up to **8 people** besides you, who join by tapping an invite link. Useful for a project with a customer's family, a class, or a small VIP club. It is not a [contact segment](https://docs.lazyapp.in/sending/broadcasts.md) for broadcasts.

You cannot add people yourself. You share an invite link; people choose to join.

## Before you start

Meta offers groups only to an **Official Business Account** (the blue tick) on a Cloud API number. Numbers that also use the WhatsApp Business app (coexistence) cannot use groups.

Check, and switch the feature on for a number:

```bash theme={null}
curl -X POST https://lazyapp.in/v1/groups/eligibility \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connection_uuid": "9f8b1c2d-…" }'
```

```json theme={null}
{ "connection_uuid": "9f8b1c2d-…", "eligible": false, "reason": "Groups need an Official Business Account (the blue tick). Request one in WhatsApp Manager, then check again." }
```

This reads Meta's `is_official_business_account` flag and turns the `groups` and `messages.group` [capabilities](https://docs.lazyapp.in/concepts/capabilities.md) on or off to match. In the console, **Groups** shows the same check when a number is not eligible yet.

> [!NOTE]
>
> Meta confirms most group changes on its group webhooks. LazyApp listens to `group_lifecycle_update`, `group_participants_update`, `group_settings_update` and `group_status_update` and keeps your groups in step; you get the matching LazyApp [events](#webhooks).

## Limits

| Limit | Value |
| - | - |
| People per group, besides you | 8 |
| Groups per business number | 10,000 |
| Messages you can send | Text, media, and text- or media-based templates |
| Not supported | Interactive messages, authentication templates, commerce messages, calls |

## Create a group

```bash theme={null}
curl -X POST https://lazyapp.in/v1/groups \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: group-renovation-1" \
  -d '{
    "subject": "Kitchen renovation – Sharma family",
    "description": "Updates and photos from the site",
    "join_approval_mode": "approval_required"
  }'
```

| Field | Required | Notes |
| - | - | - |
| `subject` | Yes | Up to 128 characters |
| `description` | No | Up to 2048 characters |
| `join_approval_mode` | No | `auto_approve` (default) or `approval_required`, where you approve each person |
| `phone_number_id` / `connection_uuid` | No | Which number runs the group; the default number otherwise |

The group starts as `pending`. When Meta confirms, it becomes `active` and gets its `provider_group_id` and `invite_link` (you also get `group.created`).

| `status` | Meaning |
| - | - |
| `pending` | Meta is creating it |
| `active` | Ready to use |
| `failed` | Meta could not create it; `last_error` says why |
| `suspended` | WhatsApp suspended it for breaking its policies |
| `deleting` / `deleted` | Deletion requested / confirmed |

## Invite people

```bash theme={null}
curl https://lazyapp.in/v1/groups/{uuid}/invite-link -H "Authorization: Bearer $LAZYAPP_API_KEY"
```

```json theme={null}
{ "invite_link": "https://chat.whatsapp.com/AbCdEf…" }
```

`POST /v1/groups/{uuid}/invite-link/reset` makes a new link; every old link stops working.

To invite by message, Meta's Template Library has a **Group invite link** utility template. Add it to your account (in WhatsApp Manager), then send it with the group id as a body parameter. WhatsApp turns it into the invite link on delivery:

```json theme={null}
{
  "type": "template",
  "to": "+919812345670",
  "template": {
    "name": "group_invite",
    "language": "en",
    "components": [
      { "type": "body", "parameters": [{ "type": "group_id", "group_id": "Y2FwaV9ncm91cDox…" }] }
    ]
  }
}
```

You can also paste the link into a 1:1 chat while the [24-hour window](https://docs.lazyapp.in/sending/messages.md#the-24-hour-window) is open.

## Approve join requests

For `approval_required` groups, people who tap the link ask to join. You get `group.join_requested`.

```bash theme={null}
curl https://lazyapp.in/v1/groups/{uuid}/join-requests -H "Authorization: Bearer $LAZYAPP_API_KEY"
```

```json theme={null}
{
  "data": [
    { "join_request_id": "MTY0Njcw…", "wa_id": "919812345670", "bsuid": null, "status": "pending", "requested_at": "2026-10-20T10:12:00+00:00", "error_message": null }
  ],
  "next_cursor": null
}
```

Approve or reject one or many:

```bash theme={null}
curl -X POST https://lazyapp.in/v1/groups/{uuid}/join-requests/approve \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "join_request_ids": ["MTY0Njcw…"] }'
```

```json theme={null}
{ "approved": ["MTY0Njcw…"], "failed": [] }
```

`/join-requests/reject` works the same way and answers with `rejected`. Meta answers per request, so a partial failure (for example a full group) is listed in `failed` with a plain `message` instead of failing the whole call.

## Members

`GET /v1/groups/{uuid}/participants` lists who is in the group (`?include_left=1` adds people who left or were removed; `?refresh=1` re-reads the list from Meta first).

Remove people (they cannot rejoin with the invite link):

```bash theme={null}
curl -X DELETE https://lazyapp.in/v1/groups/{uuid}/participants \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": ["+919812345670"] }'
```

## Send to the group

Use [`POST /v1/messages`](https://docs.lazyapp.in/sending/messages) with the group as the recipient:

```json theme={null}
{
  "type": "text",
  "recipient": { "type": "group_id", "value": "Y2FwaV9ncm91cDox…" },
  "body": "Tiles arrive tomorrow at 10."
}
```

* Messages from members arrive as `message.received` with `data.message.group` set (`uuid`, `provider_group_id`). They belong to the group, not to a 1:1 chat with that person.
* Statuses come per member and may be grouped together by Meta.
* **Pricing:** WhatsApp charges each delivered copy, so a billable message to a group of 5 costs up to 5 messages. When any member messages the group, a customer-service window opens for the whole group.

### Pin a message

```bash theme={null}
curl -X POST https://lazyapp.in/v1/groups/{uuid}/pins \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_id": "wamid.HBgLM…", "expiration_days": 7 }'
```

Pins last 1 to 30 days; send `"action": "unpin"` to remove one. Only three messages can be pinned; a fourth unpins the oldest.

## Change or delete the group

* `PATCH /v1/groups/{uuid}` with `subject` and/or `description`.
* `POST /v1/groups/{uuid}/photo` with a multipart `photo`: a **square JPEG**, at least 192 × 192 pixels, at most 5 MB.
* `DELETE /v1/groups/{uuid}` deletes the group for everyone, including you. It shows `deleting` until Meta confirms (`group.deleted`).

`POST /v1/groups/sync` loads groups that exist on the number but not yet in LazyApp, for example ones created before you connected.

## Webhooks

| Event | When |
| - | - |
| `group.created` | Meta created the group (with `invite_link`), or creation failed (`errors`) |
| `group.updated` | Name, description or photo changed, per part (`changed`, `errors`) |
| `group.deleted` | The group was deleted |
| `group.participants_changed` | Someone joined (`added`) or left / was removed (`removed`, `initiated_by`) |
| `group.join_requested` | Someone asked to join, or cancelled (`cancelled: true`) |
| `group.suspended` | WhatsApp suspended the group (`suspended: true`) or lifted it |

## Errors in plain words

| Meta code | What it means |
| - | - |
| `131215` | This number cannot use groups yet (needs the blue tick) |
| `131214` | Group creation is paused after too many marketing messages in 7 days |
| `131211` | The number already has 10,000 groups |
| `131204` | The group is full |
| `131207` | The group is suspended |
| `131208` | Too many group changes in a short time; try again shortly |
| `131020` | Nobody has joined yet, so there is no one to message |
| `131041` | The group was not found |

## In the console

**Groups** lists your groups with their status and members. Open one to chat with the group, approve join requests, remove people, copy or reset the invite link, rename it, change its photo, pin messages and delete it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.