WhatsApp group or community, and which one to build on

Most conversations about WhatsApp groups and communities are about which one to use for a club, a course or a broadcast list. The version a developer needs is narrower and harder: which one can you actually build on, and what is the block you will hit at eight participants.

#The difference in one line

A group is a conversation. A community is a container that holds groups. Everything else follows from that.

A community is the right shape when you need one announcement point and many topic groups. A group is the right shape for one conversation.

#The block nobody can skip

Here is the part that decides your architecture. WhatsApp's official group API is limited to Official Business Accounts, and the eligibility rules are not negotiable.

• The account must be an Official Business Account.
• The business must have been on the Cloud API for at least 30 days.
• Business Verification and two-step verification both completed.
• The business name is approved.
• Meta decides, and there is no guarantee.
• After a rejection you wait 30 days before trying again.
• The cap is 8 participants per group.
• Groups are created by invite link only.
• Members cannot be edited or removed through the API.

Read that list again and you will see the shape of it: 8 participants, invite links only, no removal. That is not a limitation you engineer around. It is a different product.

#What a linked device can do instead

A number linked as a device is a WhatsApp client, so it uses the client's own capabilities. Nothing is capped at 8, and members can be added and removed directly.

The row that matters most is the second one. Without removal you cannot moderate a group through the official API at all, and a group you cannot moderate is a support ticket waiting to happen.

#Reading a group

Reading is the part teams underestimate. Membership and settings arrive as group.updated, and a participant change is not an event you have to subscribe to separately.

const group = await wuapi.groups.create(accountId, {
  name: "Night shift",
  participants: ["+584241112233", "+584141234567"],
})
console.log(group.id) // 120363041234567890@g.us

const results = await wuapi.groups.addParticipants(accountId, group.id, ["+584121112222"])
for (const r of results.items) {
  if (r.error) console.log(r.contactId, r.error, r.inviteCode)
}

group.id ends in @g.us, and you pass it straight as to on a send. A group is just another chat, as far as the send endpoint is concerned.

#Announcement-only, without a community

The most common use of a community is a place to post and a place to talk. You can have both in two plain groups, or in one group where only admins send.

await wuapi.groups.update(accountId, group.id, {
  announce: true, // only admins send
  locked: true, // only admins edit the group info
})

A community is worth it when you genuinely need a parent: several topic groups, one announcement point, and a rule that a member of the community is trusted. It is worth it for an organisation with departments. It is not worth it for a team that wants a quiet channel.

const community = await wuapi.groups.create(accountId, {
  name: "Acme Academy",
  participants: [],
  community: true,
})
const track = await wuapi.groups.create(accountId, {
  name: "Track 1: backend",
  participants: ["+584241112233"],
  community: true,
})
console.log(community.community, track.community) // true true

participants may be empty on a community, which is the one place that is allowed.

#What actually changes for a member

This is the part people get wrong, so it is worth being explicit. In WhatsApp, a community member sees the community and the groups they have joined. They do not see every group in it.

To get someone into the Night shift group, they have to accept an invite to that group. They can be a member of the community and never see a single group in it.

The muted box is the one to design around. A community is not a broadcast list that everyone is subscribed to. It is a directory with permissions.

#Communities and announcements, side by side

#Channels, briefly

A channel is one-directional: admins post, subscribers read, nobody replies. It is not a group and not a community, and it is the right shape for a broadcast you do not want replies in.

You can post to a channel from a linked device with text, image, video or document, and nothing else: no replies, no mentions, no mention-all. The channels reference has the detail.

#Moderation, which is the real reason to care

Everything above is design. This part is operations, and it is what actually decides whether you can run a WhatsApp group without a human watching it.

A group that cannot be moderated is a group that degrades. People leave, the group gets quieter, the link gets shared somewhere it should not, and eventually somebody in it is being harassed by a stranger who found an invite link. There is no report button, no admin panel and no audit log on the group itself. What you have is the participant list and the permissions you have over it.

With a linked device you have the whole set, and each of these is one call:

// Leave. The last two are the ones the official API does not offer.
await wuapi.groups.removeParticipants(accountId, groupId, [spammer])
await wuapi.groups.promote(accountId, groupId, [trusted])
await wuapi.groups.update(accountId, groupId, { locked: true })
const requests = await wuapi.groups.listJoinRequests(accountId, groupId)

Removing somebody is the one that matters and the one that is impossible through the official group API. If your product has groups, that single capability is usually enough to settle the architecture question.

The inviteCode result is the other half of the story. When somebody's privacy settings stop you adding them, the result tells you and hands you a code to send them. Nobody is added without agreeing to it, and the result tells you which case you are in, so a moderation flow can handle both.

#Managing at scale, if you have to

A platform with one group per customer needs the same four operations plus one more: knowing which groups exist. That is one paginated list, and it is the call your health check should make.

let page = await wuapi.groups.list(accountId)
const groups = []
for (;;) {
  groups.push(...page.items)
  if (!page.nextCursor) break
  page = await wuapi.groups.list(accountId, { cursor: page.nextCursor })
}

Group state syncs to the phone and every linked device, so a change you make over the API is the same change the owner sees in their app. There is no separate world to reconcile. What does arrive as events is group.updated for membership and settings, group.join_requested and group.join_request_revoked for pending requests, and nothing at all for the full history replay right after linking, which is deliberately not delivered.

#The vocabulary, because WhatsApp uses it loosely

Most confusion in this area is vocabulary rather than capability, so it is worth fixing the words before the architecture.

• A group is a chat with a participant list. Everyone in it can see the messages unless the group is announcement-only.
• A community is a parent for groups. It has its own participant list and its own groups, and members join each group individually.
• A channel is one-directional. Admins post, subscribers read, and there is no participant chat at all. The API calls it a newsletter, and the docs use that word on purpose so nobody confuses it with a group.
• A group invite link is a URL that joins somebody to a group. It is the only way to create a group through the official API, and with a linked device it is just one of the ways in.
• `privacy_restricted` is the result you get back when somebody's settings stop you adding them, along with an inviteCode to send instead. Every group operation is listed in the groups reference, and communities add subgroups on top of it.

The one that catches teams out is community. A community does not subscribe anybody to anything. Adding a hundred people to a community gives you a hundred people who can see the community and none of its groups, which is a different product from what most people picture when they hear the word.

#Size limits, stated once

The per-group figure of 1,024 is the limit a linked device meets, and it is the same figure a person meets in the app. That consistency is the argument for using a linked device: you get the limits your own users already understand, rather than a set of numbers that exist only in an API contract.

Group cap

1,024 participants, the same as the app

Official API cap

8 participants, and invitation links to create one

Official API eligibility

Official Business Account, 30 days on the Cloud API, verification, 30 days to retry a rejection

Removal

possible with a linked device, not possible through the official group API

Announcement-only

a setting on any group, community or not

#Which one to build on

For a developer, the decision is mostly about whether you need removal and whether you can get an Official Business Account approved.

• You need to add and remove people, or promote admins: a linked device. No 8 person cap, removal works, no eligibility rules.
• You need one announcement point and many topic groups, and members accept that groups are opt-in: a community.
• You need post-only, no replies ever, and no membership management: a channel.
• You need a public directory that strangers can find and join by link: invite links on a group or a community, and nothing else.

If you are choosing between a group and a community for a product, pick the group. Add a community when you have real subgroups, not before.

#Questions people ask

#Where to go next

The groups reference lists every operation and the communities reference covers subgroups. Building a WhatsApp chatbot is about what a bot does once it is in a group, and the WhatsApp QR code covers linking the number that owns the group.