Skip to Content
Communities

Community

client.community exposes the CommunityModule, which covers every operation you can perform on a WhatsApp Community from zaileys. A WhatsApp Community is essentially a group-of-groups: one parent entity (the community) links multiple regular group chats under it, giving members a shared announcement space and a directory of sub-groups. Community JIDs use the same xxx@g.us format as regular groups.

import { Client } from 'zaileys' const client = new Client() client.on('connect', async () => { const community = await client.community.create('Devs Hub', 'Welcome to the hub') console.log('Community created:', community.id) })
🚫

NOT_CONNECTED guard. Every client.community method calls requireSocket() internally. If the client is not yet connected, the call throws ZaileysDomainError with code NOT_CONNECTED and message client not connected. Always call community methods from inside a connect handler or after await client.connect(). See Error Handling.

Methods at a glance

MethodReturnsDescription
create(subject, body)Promise<GroupMetadata>Create a new community.
createGroup(subject, participants, communityId)Promise<GroupMetadata>Create a sub-group directly inside a community.
linkGroup(communityId, groupId)Promise<void>Link an existing group into the community.
unlinkGroup(communityId, groupId)Promise<void>Unlink a group from the community.
subGroups(communityId)Promise<LinkedGroup[]>List the community’s linked groups.
leave(communityId)Promise<void>Leave the community.
updateSubject(communityId, subject)Promise<void>Rename the community.
updateDescription(communityId, description?)Promise<void>Update (or clear) the community description.
inviteCode(communityId)Promise<string | undefined>Get the current invite code.
revokeInvite(communityId)Promise<string | undefined>Revoke and regenerate the invite code.
acceptInvite(code)Promise<string | undefined>Join a community via invite code.
⚠️

Ban-safety — operationGuard is active by default. create and createGroup share the community.create category (minimum interval 120 seconds). acceptInvite uses community.join (minimum interval 30 seconds). The guard serialises concurrent calls in the same category and inserts the required wait between them so rapid community creation or bulk joins never fire faster than WhatsApp tolerates. Disabling or bypassing the guard increases the risk of a temporary account restriction. See Configuration and Troubleshooting.

create

create(subject: string, body: string): Promise<GroupMetadata>

Creates a new community. subject becomes the community name; body is the announcement text shown to members when they join.

Returns GroupMetadata — the full metadata object for the newly created community, including its id (a xxx@g.us JID).

ParameterTypeDescription
subjectstringCommunity name.
bodystringAnnouncement body shown on join.
const community = await client.community.create( 'Devs Hub', 'A space for developers using zaileys.', ) console.log('Community id:', community.id) // e.g. "120363000000000001@g.us"

createGroup

createGroup(subject: string, participants: string[], communityId: string): Promise<GroupMetadata>

Creates a new regular group and immediately links it into the specified community. Participants are added at creation time. Returns GroupMetadata for the new group.

ParameterTypeDescription
subjectstringGroup name.
participantsstring[]Array of user JIDs (628xxxxxxxxxx@s.whatsapp.net) to add.
communityIdstringCommunity JID (xxx@g.us).
const communityId = '120363000000000001@g.us' const group = await client.community.createGroup( 'Backend Team', [ '628111111111@s.whatsapp.net', '628222222222@s.whatsapp.net', ], communityId, ) console.log('Sub-group created:', group.id)

linkGroup

linkGroup(communityId: string, groupId: string): Promise<void>

Links an existing group into the community. The group must exist and the bot must have the necessary permissions in both the group and the community.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
groupIdstringGroup JID to link (xxx@g.us).
const communityId = '120363000000000001@g.us' const groupId = '120363000000000002@g.us' await client.community.linkGroup(communityId, groupId) console.log('Group linked.')

unlinkGroup

unlinkGroup(communityId: string, groupId: string): Promise<void>

Removes a group from the community without deleting the group itself. The group continues to exist as a standalone group.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
groupIdstringGroup JID to unlink (xxx@g.us).
await client.community.unlinkGroup(communityId, groupId) console.log('Group unlinked.')

subGroups

subGroups(communityId: string): Promise<LinkedGroup[]>

Returns the list of groups currently linked to the community. Each entry is a LinkedGroup object.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).

LinkedGroup shape

FieldTypeDescription
idstring | undefinedGroup JID.
subjectstringGroup name.
creationnumber | undefinedUnix timestamp of group creation.
ownerstring | undefinedJID of the group owner.
sizenumber | undefinedNumber of members.
const communityId = '120363000000000001@g.us' const groups = await client.community.subGroups(communityId) for (const g of groups) { console.log(g.subject, '—', g.size, 'members') }

leave

leave(communityId: string): Promise<void>

Leaves the community. The bot’s account is removed from the community and all its sub-groups that were joined through it.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
await client.community.leave('120363000000000001@g.us')

updateSubject

updateSubject(communityId: string, subject: string): Promise<void>

Renames the community. Requires admin rights in the community.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
subjectstringNew community name.
await client.community.updateSubject('120363000000000001@g.us', 'Devs Hub v2')

updateDescription

updateDescription(communityId: string, description?: string): Promise<void>

Updates the community description. Passing undefined (or calling with only one argument) clears the description.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
descriptionstring | undefinedNew description. Omit or pass undefined to clear.
// Set a new description await client.community.updateDescription( '120363000000000001@g.us', 'Open community for zaileys developers.', ) // Clear the description await client.community.updateDescription('120363000000000001@g.us')

inviteCode

inviteCode(communityId: string): Promise<string | undefined>

Returns the current invite code string for the community, or undefined if none is available. Append the code to https://chat.whatsapp.com/ to form a sharable link.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
const code = await client.community.inviteCode('120363000000000001@g.us') if (code) { console.log('Invite link: https://chat.whatsapp.com/' + code) }

revokeInvite

revokeInvite(communityId: string): Promise<string | undefined>

Invalidates the current invite code and issues a new one. Returns the new code, or undefined on failure. Use this when the existing link has been shared too broadly.

ParameterTypeDescription
communityIdstringCommunity JID (xxx@g.us).
const newCode = await client.community.revokeInvite('120363000000000001@g.us') if (newCode) { console.log('New invite link: https://chat.whatsapp.com/' + newCode) }

acceptInvite

acceptInvite(code: string): Promise<string | undefined>

Joins a community using an invite code. Returns the community JID on success, or undefined.

⚠️

acceptInvite is guarded by the community.join category with a 30-second minimum interval. Joining multiple communities in quick succession will be automatically spaced by the operationGuard. See Configuration.

ParameterTypeDescription
codestringThe invite code (just the code portion, not the full URL).
// Extract just the code from a full URL if needed const url = 'https://chat.whatsapp.com/AbCdEfGhIjKlMnOpQrStUv' const code = url.split('/').pop()! const communityId = await client.community.acceptInvite(code) console.log('Joined community:', communityId)

Complete example

The following example creates a community, creates two sub-groups inside it, lists them, then updates the community name.

import { Client } from 'zaileys' const client = new Client({ sessionId: 'community-bot' }) client.on('connect', async () => { // 1. Create the community const community = await client.community.create( 'Devs Hub', 'Central space for all zaileys developers.', ) console.log('Community:', community.id) // 2. Create sub-groups inside it const backend = await client.community.createGroup( 'Backend', ['628111111111@s.whatsapp.net'], community.id, ) const frontend = await client.community.createGroup( 'Frontend', ['628222222222@s.whatsapp.net'], community.id, ) console.log('Groups created:', backend.id, frontend.id) // 3. List linked groups const groups = await client.community.subGroups(community.id) console.log('Sub-groups:', groups.map((g) => g.subject)) // 4. Rename the community await client.community.updateSubject(community.id, 'Devs Hub v2') // 5. Get an invite link const code = await client.community.inviteCode(community.id) if (code) { console.log('Share:', 'https://chat.whatsapp.com/' + code) } })

Error handling

All client.community methods throw ZaileysDomainError on failure. The most common codes are:

CodeWhen it occurs
NOT_CONNECTEDMethod called before the client has connected.
import { Client, ZaileysDomainError } from 'zaileys' try { await client.community.create('Test', 'body') } catch (err) { if (err instanceof ZaileysDomainError && err.code === 'NOT_CONNECTED') { console.error('Connect the client first.') } else { throw err } }

See Error Handling for the full error hierarchy and all codes.

See also

  • Groups — create and manage regular WhatsApp groups.
  • Newsletter — WhatsApp Channels (newsletters).
  • Configuration — tune or disable operationGuard intervals.
  • Troubleshooting — what to do when operations are being rate-limited.
Last updated on