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

# WhatsApp Groups

> Create and manage WhatsApp groups via the Chirp API

The WhatsApp Groups API lets you create and manage groups directly through the WhatsApp Business Platform. Groups allow your business phone number to communicate with up to 8 participants simultaneously.

<Warning>
  WhatsApp Groups require an **Official Business Account (OBA)** status on your WhatsApp phone number. Contact Meta support to request OBA verification if you haven't already.
</Warning>

## Prerequisites

* A WhatsApp phone number connected to Chirp
* Official Business Account (OBA) status on that phone number
* An active app key (`sk_live_app_*` or `sk_test_app_*`)

## Key Limits

| Limit                           | Value                              |
| ------------------------------- | ---------------------------------- |
| **Max participants per group**  | 8 (including your business number) |
| **Max groups per phone number** | 10,000                             |
| **Group subject length**        | 1-60 characters                    |
| **Group description length**    | Up to 2,048 characters             |

## Creating a Group

```bash icon="terminal" title="Create Group" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/groups \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsappPhoneNumberId": "wapn_2DbBs7GWhGvVNJGrDXr5RG0",
    "subject": "Customer Support",
    "description": "Support channel for premium customers",
    "joinApprovalMode": "auto_approve"
  }'
```

The `joinApprovalMode` controls how join requests are handled:

* `auto_approve` - Users who click the invite link join immediately
* `approval_required` - Join requests must be manually approved via the API

## Invite Links

After creating a group, generate an invite link to add participants:

```bash icon="terminal" title="Get Invite Link" theme={null}
curl https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/invite-link \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

If an invite link is compromised, reset it to invalidate the old link:

```bash icon="terminal" title="Reset Invite Link" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/invite-link/reset \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

## Managing Participants

List current group members:

```bash icon="terminal" title="List Participants" theme={null}
curl https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/participants \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

Remove participants by their WhatsApp ID:

```bash icon="terminal" title="Remove Participants" theme={null}
curl -X DELETE https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/participants \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": ["+15551234567"]
  }'
```

## Join Requests

When `joinApprovalMode` is set to `approval_required`, users who click the invite link will create join requests that you can approve or reject.

```bash icon="terminal" title="Approve Join Requests" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/join-requests/approve \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "joinRequestIds": ["join_req_123", "join_req_456"]
  }'
```

## Sending Messages

Send a message to all group participants:

```bash icon="terminal" title="Send Group Message" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "text": {
      "body": "Hello everyone!"
    }
  }'
```

Supported message types: `text`, `image`, `video`, `audio`, and `document`.

## Pinning Messages

Pin important messages so they appear at the top of the group chat:

```bash icon="terminal" title="Pin Message" theme={null}
curl -X POST https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/messages/pin \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messageId": "wamid.xxx",
    "expirationDays": 7
  }'
```

The `expirationDays` field controls how long the pin lasts (1-30 days, defaults to 7).

## Group Webhooks

When you subscribe to group webhook events, you'll receive notifications for:

| Event                                  | Description                                            |
| -------------------------------------- | ------------------------------------------------------ |
| `groups.whatsapp.created`              | A new group was created                                |
| `groups.whatsapp.deleted`              | A group was deleted                                    |
| `groups.whatsapp.settings_updated`     | Group subject, description, or profile picture changed |
| `groups.whatsapp.participant_added`    | A participant was added to the group                   |
| `groups.whatsapp.participant_left`     | A participant left the group                           |
| `groups.whatsapp.participant_removed`  | A participant was removed from the group               |
| `groups.whatsapp.join_request_created` | A new join request was received                        |
| `groups.whatsapp.join_request_revoked` | A join request was revoked                             |
| `groups.whatsapp.suspended`            | The group was suspended by WhatsApp                    |
| `groups.whatsapp.suspension_cleared`   | The group suspension was cleared                       |

<Info>
  To receive group webhooks, subscribe to the relevant events in your [webhook configuration](/concepts/webhooks).
</Info>