Skip to main content
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

LimitValue
Max participants per group8 (including your business number)
Max groups per phone number10,000
Group subject length1-60 characters
Group description lengthUp 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
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:
EventDescription
groups.whatsapp.createdA new group was created
groups.whatsapp.deletedA group was deleted
groups.whatsapp.settings_updatedGroup subject, description, or profile picture changed
groups.whatsapp.participant_addedA participant was added to the group
groups.whatsapp.participant_leftA participant left the group
groups.whatsapp.participant_removedA participant was removed from the group
groups.whatsapp.join_request_createdA new join request was received
groups.whatsapp.join_request_revokedA join request was revoked
groups.whatsapp.suspendedThe group was suspended by WhatsApp
groups.whatsapp.suspension_clearedThe group suspension was cleared
To receive group webhooks, subscribe to the relevant events in your webhook configuration.