WhatsApp groups API: create, manage and post in groups

Yes, you can run WhatsApp groups through an API. Link a WhatsApp number to Mossmoon with one QR scan and your code receives every message in every group that number is in, with the person who wrote it, and can post, create groups, add people, change settings and approve join requests over REST.

Below are the real endpoints and payloads for each part, then the limits to design around. All of it is on the $15 per line plan; see it at a glance in the groups features.

Is there an official WhatsApp groups API?#

There are two ways to automate WhatsApp groups. Meta’s WhatsApp Business API added a groups feature, but it is narrow: only Official Business Accounts can use it, groups are capped at 8 people, people join by invite link only (you can’t add them), and it doesn’t work on numbers that also use the WhatsApp Business app.

The other way is linked devices. Mossmoon links your customer’s own number as a linked device, so the API can do what a person can do in groups on their phone: be in any number of groups, of normal size, and run them as an admin. It works on personal WhatsApp and the Business app alike, with no business verification or message templates. Our Business API vs personal API explainer goes deeper on choosing between the two.

How do I receive WhatsApp group messages?#

Every message in a group the line belongs to arrives on your webhook as message.received with is_group: true. The group itself is the sender (from_wa_id ends in @g.us), and the author_* fields tell you which member actually wrote it.

POST https://your-app.com/webhooks/whatsapp
X-Mossmoon-Event: message.received
X-Mossmoon-Signature: sha256=...

{
  "event": "message.received",
  "line_id": "wa_8f3c2e1a",
  "ts": "2026-10-16T09:14:03.120Z",
  "data": {
    "message_id": "wamsg_xyz",
    "is_group": true,
    "addressing": "group",
    "from_wa_id": "[email protected]",
    "from_e164": null,
    "author_wa_id": "[email protected]",
    "author_e164": "+15552017788",
    "text": "Is the 9am still on Saturday?",
    "type": "chat"
  }
}

• Use from_wa_id as the conversation key. It stays the same for the life of the group. GET /lines/:id/[email protected] returns the whole thread, both directions.
• author_e164 can be null. Some members are known to WhatsApp only by an internal id ending in @lid. Key people on author_wa_id, and show author_username when they have one.
• History, when shared. If whoever adds the line chooses to share recent messages (up to 100 from the last 30 days), they arrive with history: true, followed by group.history_received.

Field by field details are in the docs under identifying a group message. If you haven’t set up a webhook endpoint yet, start with the webhook setup guide.

How do I send a message to a WhatsApp group?#

Use the same send endpoint as for a one-to-one chat, with the group id as to_wa_id instead of a phone number in to. To tag someone, list them in mentions and put @ plus their number in the text where the tag goes. They see a blue tag and get notified.

curl https://mossmoon.app/api/v1/wa/lines/wa_8f3c2e1a/send \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to_wa_id": "[email protected]",
    "text": "@15552017788 yes, 9am Saturday as usual.",
    "mentions": ["+15552017788"]
  }'

await fetch("https://mossmoon.app/api/v1/wa/lines/wa_8f3c2e1a/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOSSMOON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to_wa_id: "[email protected]",
    text: "@15552017788 yes, 9am Saturday as usual.",
    mentions: ["+15552017788"],
  }),
});

requests.post(
    "https://mossmoon.app/api/v1/wa/lines/wa_8f3c2e1a/send",
    headers={"Authorization": f"Bearer {MOSSMOON_KEY}"},
    json={
        "to_wa_id": "[email protected]",
        "text": "@15552017788 yes, 9am Saturday as usual.",
        "mentions": ["+15552017788"],
    },
)

Mention everyone

Put @all in the text and add mention_all: true. Everyone in the group is mentioned and notified. As on the phone, in groups of 33 or more members only admins can do this.

{
  "to_wa_id": "[email protected]",
  "text": "@all tonight's 7pm class moves to Studio B.",
  "mention_all": true
}

Media, voice notes, polls, locations and contact cards go into groups the same way, and you can quote a group message or reply to its author privately. Reactions work in groups too. The full contract is under sending into a group.

How do I create a WhatsApp group with the API?#

One call creates the group, adds people and makes the line the owner. Here is the whole flow, from a fresh number to a group that is posting and reporting back.

1. 1

   Link the WhatsApp number

   Create a line with POST /api/v1/wa/lines and show your customer the connect_url. They scan the QR from WhatsApp’s Linked devices screen, and you get line.ready.
2. 2

   Create the group

   POST /lines/:id/groups with a name (up to 100 characters) and up to 256 participants. The line becomes the group’s owner and admin. Description, a first message and your own reference id are optional.

   RequestResponse

   POST /api/v1/wa/lines/wa_8f3c2e1a/groups
   Authorization: Bearer mm_live_...
   
   {
     "name": "Harbor Yoga Members",
     "participants": [
       "+15554041290",
       "+15553182290",
       "+447700900123"
     ],
     "description": "Class changes and studio news.",
     "initial_message": "Welcome! Class updates go here.",
     "invite_message": "Join our members group",
     "agency_external_group_id": "studio_42_members"
   }

3. 3

   Handle everyone who wasn't added

   Each person comes back with a status. WhatsApp lets people choose who can add them to groups, so some get a private invite from the line (invite_sent) and some need the invite_link sent to them (invite_required).
4. 4

   Post into the group

   Send with POST /lines/:id/send and the group id as to_wa_id. Text, media, polls and voice notes all work, with mentions.
5. 5

   Listen for group webhooks

   Store group_wa_id and handle message.received with is_group: true, plus the group.* events for joins, leaves, settings and join requests.

How do I add or remove people from a group?#

POST /lines/:id/groups/:group_id/participants adds people and DELETE on the same path removes them. The line must be an admin of the group, otherwise you get 403 not_group_admin. A participant can be a phone number, a WhatsApp id, or a WhatsApp username such as @priya.n (with their PIN if they set one).

POST /api/v1/wa/lines/wa_8f3c2e1a/groups/[email protected]/participants
Authorization: Bearer mm_live_...

{ "participants": ["+15552017788", "@priya.n"] }

Less common answers are recently_left, already_in_group, group_full and failed, which carries an error field. Removals come back removed, not_in_group or failed.

Private invites you no longer want can be cancelled with /invites/cancel.

Can I use invite links and join groups by link?#

Yes. The line handles links the way a phone does:

• GET /groups/:group_id/invite-link returns the link, and POST .../invite-link/revoke resets it so the old one stops working.
• POST /groups/invite-info previews a link (name, size, description, whether approval is needed) without joining.
• POST /groups/join joins from a link. It returns joined, or requested when an admin has to approve first.
• When someone sends the line a private invite, it arrives as a message of type groups_v4_invite, and POST /invites/:message_id/accept accepts it.

Either way, group.joined fires once the line is in. Details: join groups and invite links.

How do I manage admins and group settings?#

Promote members with POST /groups/:group_id/admins and dismiss them with DELETE on the same path. Each person comes back promoted, demoted, not_in_group or failed, read from WhatsApp’s own group data.

Every setting from the phone’s group permissions screen is one PATCH away. Send only the fields you want to change.

PATCH /api/v1/wa/lines/wa_8f3c2e1a/groups/[email protected]
Authorization: Bearer mm_live_...

{
  "messages_admins_only": true,
  "approval_required": true,
  "disappearing_seconds": 604800
}

disappearing_seconds takes 0 (off), 86400, 604800 or 7776000. The name and description go in the same call, the picture has its own PUT .../picture with an image URL, and POST .../leave takes the line out of a group. See admins and settings in the docs.

How do group join requests work?#

With approval_required on, people who open the invite link ask to join instead of joining. Each request reaches you as a webhook with a ready-made approve_url you can POST to with your API key.

{
  "event": "group.join_requested",
  "line_id": "wa_8f3c2e1a",
  "data": {
    "group_wa_id": "[email protected]",
    "requester_wa_id": "103414994325753@lid",
    "requester_e164": "+18186197142",
    "approve_url": "https://mossmoon.app/api/v1/wa/lines/wa_8f3c2e1a/groups/1203630123%40g.us/requests/approve"
  }
}

GET /groups/:group_id/requests lists what is pending, and POST .../requests/approve or .../requests/reject handles one person, a list, or everyone when you leave requesters out. Approved people then arrive as group.participant_added.

Which group webhooks will I get?#

Membership and settings changes arrive as their own events, whether they were made through the API or on someone’s phone. None of them are stored as messages.

group.participant_removed mirrors participant_added, and group.left carries left_by_line: true when the line left on its own. Payloads for each are in group webhook events.

What are the limits of the WhatsApp groups API?#

Design around these from day one:

• Store group ids as you see them. There is no groups directory endpoint. You get each id when the line joins (group.joined), from its first message, or when you create the group, and GET /lines/:id/chats?type=group lists the group chats already on the linked device.
• Only groups the line is in. WhatsApp only shows group details to members, so after the line leaves, GET /groups/:id reports line_is_member: false.
• Admin rights for admin things. Adding people, settings, links and requests need the line to be a group admin, just as on the phone.
• 256 people per create call. Add more afterwards through /participants.
• Daily send caps. A message into a group counts as one send, however many members it reaches. Warmed lines get a soft cap of 750 and a hard cap of 1,500 sends a day (rate limits).
• Go slow on new groups. WhatsApp rate-limits group creation per device. A few per customer per day is safe; hundreds from a fresh number is not.
• No history for people the line adds. WhatsApp doesn’t let a linked device share past messages with new members.

Mossmoon vs goghl.ai for WhatsApp groups#

goghl.ai also links WhatsApp by QR, inside GoHighLevel. It can read and send group messages and add or remove members from a workflow, so those aren’t listed here. These are the group features we offer that their public docs don’t list.

For Meta’s Business API the gap is wider: its groups hold at most 8 people, are invite only and need an Official Business Account (Meta’s groups docs). The full three-way table is on the features page.

Frequently asked questions#