WhatsApp Groups

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.

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.

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

Create Group

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:

Get Invite Link

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:

Reset Invite Link

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:

List Participants

curl https://api.buildwithchirp.com/v1/whatsapp/groups/{groupId}/participants \
  -H "Authorization: Bearer YOUR_APP_KEY"

Remove participants by their WhatsApp ID:

Remove Participants

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.

Approve Join Requests

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:

Send Group Message

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:

Pin Message

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

To receive group webhooks, subscribe to the relevant events in your webhook configuration.

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

WhatsApp Groups

Prerequisites

Key Limits

Creating a Group

Invite Links

Managing Participants

Join Requests

Sending Messages

Pinning Messages

Group Webhooks

​Prerequisites

​Key Limits

​Creating a Group

​Invite Links

​Managing Participants

​Join Requests

​Sending Messages

​Pinning Messages

​Group Webhooks

Prerequisites

Key Limits

Creating a Group

Invite Links

Managing Participants

Join Requests

Sending Messages

Pinning Messages

Group Webhooks