API reference · new in 1.1.0
whatsapp.groups
Create and manage WhatsApp groups, share invite links, handle join requests, and message the group.
create
| Parameter | Type | Description |
|---|---|---|
| subject* | string | Group name. Max 128 characters. |
| description | string | Max 2048 characters. |
| joinApprovalMode | "approval_required" | "auto_approve" | Defaults to "auto_approve" on Meta's side. |
The group ID and invite link are delivered via the group_lifecycle_update webhook (a group_update event). The create response shape is not documented by Meta, so inspect raw.
const { raw, error } = await whatsapp.groups.create({
subject: "VIP customers",
description: "Early access and offers",
joinApprovalMode: "approval_required",
});
whatsapp.webhooks.on("group_update", (e) => {
if (e.field === "group_lifecycle_update") console.log(e.value); // group ID + invite link
});list & get
get returns only the ID unless you request fields: subject, description, join_approval_mode, suspended, creation_timestamp, participants, total_participant_count.
const { data: page } = await whatsapp.groups.list({ limit: 25 });
page?.data.groups.forEach((g) => console.log(g.id, g.subject));
const { data: group } = await whatsapp.groups.get("120363012345678901", [
"subject",
"participants",
"total_participant_count",
]);update & delete
Deleting a group removes every participant, including the business. Profile pictures need a multipart upload and are not supported yet.
await whatsapp.groups.update(groupId, { subject: "VIP customers 2026" });
await whatsapp.groups.delete(groupId);Invite links
const { data } = await whatsapp.groups.getInviteLink(groupId);
console.log(data?.invite_link);
// Generates a new link; previously shared links stop working
await whatsapp.groups.resetInviteLink(groupId);Join requests & participants
removeParticipants removes up to 8 participants (phone numbers or wa_ids). Removed users cannot rejoin via the invite link.
const { data } = await whatsapp.groups.listJoinRequests(groupId);
const ids = data?.data.map((r) => r.join_request_id) ?? [];
await whatsapp.groups.approveJoinRequests(groupId, ids);
// or: await whatsapp.groups.rejectJoinRequests(groupId, ids);
await whatsapp.groups.removeParticipants(groupId, ["15551234567"]);Sending to a group
Pass the group ID as to and set recipientType: "group" in the send options of any messages method:
await whatsapp.messages.sendText(
groupId,
{ body: "Welcome to the VIP group!" },
{ recipientType: "group" }
);