Group chats

By the end of this page, your number owns a WhatsApp group with participants in it. Messages to the group flow through the same inbox endpoints as 1:1 conversations.

These are real WhatsApp groups on the platform, not the contact segments broadcasts target.

Before you start

You need a connected WhatsApp account on a Cloud API-only number that Meta has granted Official Business Account (OBA) status.

Coexistence means Cloud API and the WhatsApp Business app on the same number. Meta disables group create, list and management endpoints there and for Multi-solution Conversations setups.

Step 1: Create a group

Call POST /v1/whatsapp/wa-groups with accountId and subject (at most 128 characters).

Set joinApprovalMode:

• approval_required makes people who use the invite link wait for approval.
• auto_approve lets them straight in.

import Zernio from '@zernio/node';

const zernio = new Zernio();
const accountId = '66b2e19d8c3f5a7e9d0b1c2d';

const { data: created } = await zernio.whatsapp.createWhatsAppGroupChat({
  body: {
    accountId,
    subject: 'Customer Support Team',
    description: 'Internal support coordination',
    joinApprovalMode: 'approval_required'
  }
});

const groupId = created.group.groupId;

Response (201):

{
  "success": true,
  "group": {
    "groupId": "120363418596621542",
    "inviteLink": "https://chat.whatsapp.com/..."
  }
}

group.groupId is the groupId for every call below.

List the number's active groups with GET /v1/whatsapp/wa-groups?accountId=.... It returns groups[] with id, subject and createdAt, paginated with after.

Step 2: Add participants

Call POST /v1/whatsapp/wa-groups/{groupId}/participants with accountId in the query and up to 8 phoneNumbers in E.164. The same path with DELETE removes them.

Meta limits. A group holds at most 8 participants in total, and a number can own up to 10,000 groups.

Meta documents groups as invite-only, so people normally join through the invite link in Step 3.

const { data: added } = await zernio.whatsapp.addWhatsAppGroupParticipants({
  path: { groupId },
  query: { accountId },
  body: { phoneNumbers: ['+13105551234', '+442071234567'] }
});

console.log(added.message);

await zernio.whatsapp.removeWhatsAppGroupParticipants({
  path: { groupId },
  query: { accountId },
  body: { phoneNumbers: ['+442071234567'] }
});

Response (200), the add:

{
  "success": true,
  "message": "Participants added"
}

Response (200), the remove:

{
  "success": true,
  "message": "Participants removed"
}

Step 3: Invite links and join requests

POST /v1/whatsapp/wa-groups/{groupId}/invite-link creates a fresh invite link and revokes the previous one.

For a group with approval_required, use /v1/whatsapp/wa-groups/{groupId}/join-requests:

• GET lists who is waiting.
• POST with phoneNumbers lets them in.
• DELETE rejects them.

const { data: link } = await zernio.whatsapp.createWhatsAppGroupInviteLink({
  path: { groupId },
  query: { accountId }
});

console.log(link.inviteLink);

const { data: pending } = await zernio.whatsapp.listWhatsAppGroupJoinRequests({
  path: { groupId },
  query: { accountId }
});

await zernio.whatsapp.approveWhatsAppGroupJoinRequests({
  path: { groupId },
  query: { accountId },
  body: { phoneNumbers: pending.joinRequests.map(r => r.user) }
});

Response (200), the new invite link, which revokes the previous one:

{
  "success": true,
  "inviteLink": "https://chat.whatsapp.com/..."
}

Response (200), the waiting phones with the Unix timestamp of each request:

{
  "success": true,
  "joinRequests": [
    { "user": "+13105551234", "timestamp": 1788084000 }
  ]
}

Response (200), the approval:

{
  "success": true,
  "message": "Requests approved"
}

Step 4: Message the group

A group becomes a conversation in the inbox when the first message arrives in it. Every participant's messages land there afterwards.

Nothing you have called so far creates that conversation. A participant has to send the first message, since there is no endpoint that opens a group conversation from your side.

When it arrives, message.received carries the conversationId. List conversations shows it from then on.

With that id, send with POST /v1/inbox/conversations/{conversationId}/messages and accountId plus message, the same call as a 1:1 conversation.

const { data: sent } = await zernio.messages.sendInboxMessage({
  path: { conversationId: '66c3d2ae7b4f6c8d0e1f2a3b' },
  body: { accountId, message: 'Welcome to the support team group.' }
});

console.log(sent.data.messageId);

Response (200):

{
  "success": true,
  "data": {
    "messageId": "wamid.HBgLMTMxMDU1NTEyMzQVAgARGBI5QTNEMEY3RjQ4RjE2QjA3QzYA",
    "conversationId": "66c3d2ae7b4f6c8d0e1f2a3b"
  }
}

If it fails

On a coexistence number, a 400 from any group endpoint is Meta refusing the call. type is platform_error, and platformError carries Meta's own code and message verbatim.

Check the number in Meta Business Suite. If it is still registered in the WhatsApp Business app, take it out of coexistence and reconnect it with onboarding=api (coexistence).

More than 8 numbers. A 400 on Step 2 is the group limit, not a batch size. Splitting the list across requests does not take a group past 8 participants, so use broadcasts to reach more people.

Every error uses the envelope in error handling.

Related

• Connection & Setup: how to end up with a Cloud API-only number.
• WhatsApp inbox: everything you can send into a group conversation.
• Groups API: get, update, delete and reject join requests.
• Broadcasts: reach many people 1:1 instead of in a group.