API reference · new in 1.1.0

whatsapp.groups

Create and manage WhatsApp groups, share invite links, handle join requests, and message the group.

Participants cannot be added directly. Share the invite link (for example in a template) and approve join requests. Every method resolves to the usual { data, error } result.

create

whatsapp.groups.create(input: CreateGroupInput, opts?: { phoneNumberId?: string })
ParameterTypeDescription
subject*stringGroup name. Max 128 characters.
descriptionstringMax 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

whatsapp.groups.list(params?: { limit?: number; after?: string; before?: string }, opts?)
whatsapp.groups.get(groupId: string, fields?: GroupField[]): Promise<WhatsappResponse<WhatsappGroup>>

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

whatsapp.groups.update(groupId: string, input: { subject?: string; description?: string })
whatsapp.groups.delete(groupId: string)

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

whatsapp.groups.getInviteLink(groupId: string)
whatsapp.groups.resetInviteLink(groupId: string)
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

whatsapp.groups.listJoinRequests(groupId: string)
whatsapp.groups.approveJoinRequests(groupId: string, joinRequestIds: string[])
whatsapp.groups.rejectJoinRequests(groupId: string, joinRequestIds: string[])
whatsapp.groups.removeParticipants(groupId: string, users: string[])

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" }
);