WhatsApp Groups API: How to Create and Message Groups

The WhatsApp Groups API lets a business create a WhatsApp group from code, post messages to it, and manage who is in it. It is part of Meta's Cloud API. Your number needs the verified badge, it cannot also run in the WhatsApp Business app, and a group holds 8 people at most.

What the Groups API is for#

Most WhatsApp Business API traffic is one business talking to one customer. Groups are different. A group has a name, a small set of members, and an invite link. People join by tapping that link.

That fits internal alerts, a small team room, a project group per client, or a support group for a handful of people. It does not fit a broadcast to hundreds of customers. For that, use approved templates in one-to-one chats.

Instant Reply exposes Meta's Groups API as a REST API at https://api.instantreply.co/v1 and as tools on the MCP server. This guide uses that API for its examples. The limits come from Meta.

Who can use it#

Meta sets the rules. Three conditions must hold:

1. Your WhatsApp number is connected to the platform you call. With Instant Reply, that means a connected WhatsApp number.
2. Your number has the verified badge. Meta calls this an Official Business Account.
3. Your number is not also used in the WhatsApp Business phone app. Meta does not offer groups for those numbers.

Do not guess. Ask the API. The eligibility call returns eligible, and when it is false it returns one reason.

curl https://api.instantreply.co/v1/whatsapp/groups/eligibility \
  -H "Authorization: Bearer $IR_API_KEY"

# {"eligible": false, "reason": "not_official_business_account"}

If you call a create or send endpoint anyway, a number that fails the check gets a 422 with the code GROUPS_INELIGIBLE.

Create a group with one API call#

Send a subject of 1 to 128 characters. A description of up to 512 characters is optional. No other fields are accepted.

curl -X POST https://api.instantreply.co/v1/whatsapp/groups \
  -H "Authorization: Bearer $IR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Alerts", "description": "Hot leads and cancellations"}'

# 200 OK
# {"group_id": "...", "invite_link": "https://..."}

Save the group_id. You need it for every later call. Share the invite_link with the people who should join. A missing or too long subject returns 400.

The API key goes in an Authorization: Bearer header. The older X-API-Key header still works. Reading groups needs the scope conversations:read. Writing needs messages:send.

Send a message to the group#

Send either plain text or an approved template. Pass one of the two, never both. Text can be 1 to 4,096 characters.

curl -X POST https://api.instantreply.co/v1/whatsapp/groups/GROUP_ID/messages \
  -H "Authorization: Bearer $IR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hot lead: Dana asked for a quote 2 minutes ago."}'

For a template, send its name and language. Components are optional.

-d '{"template": {"name": "alert_notice", "language": "en"}}'

Groups do not support buttons. Meta does not allow interactive messages in groups, so the API takes text and templates only. The API does not send media. Meta's own page says groups support media, but this API does not expose it.

Every group id is checked against your own number before anything runs. An id that is not yours returns 404 with GROUP_NOT_FOUND.

Manage the group#

The rest of the endpoints cover the lifecycle of a group. All of them sit under /v1/whatsapp/groups.

Approve, reject and remove each take a list of 1 to 7 people per call. There is no endpoint to add people. Meta does not let a business add people by phone number. They join from the invite link.

The limits Meta sets#

These come from Meta's Groups API page. Meta can change them, so check the page before you build around a number.

The 8-person cap is the one that surprises people. It is a hard limit in Meta's quick facts, and nothing in the docs we read offers a way around it. If you need 50 people in one group, this API is the wrong tool.

What group messages cost#

The Groups API uses per-message pricing. Meta bills group messages in its own groups categories. The names on Meta's pricing page are group_marketing, group_utility and, from October 1, 2026, group_service. Some group messages are free. Which ones depends on the category and on a free tier that Meta describes.

We do not list rates here. They change, and they depend on your account and the recipient's market. Read Meta's Groups API pricing page for the numbers that apply to you. Instant Reply adds no fee on top of Meta's.

Example: an alerts group for your team#

Say you run a shop. You want one place where your team sees three things. A subscription is about to end, a customer is angry, or a lead is hot. Your code decides when each one happens. The API creates the group and posts the message.

1. Call the eligibility endpoint once. If it says false, fix the reason first.
2. Create a group with the subject "Alerts". Store the group_id.
3. Send the invite_link to your teammates yourself, by email or in your team chat. They tap it to join.
4. When your system sees a hot lead, post one line to the group.
5. When a teammate leaves, remove their number from the group.

Keep each alert short and put the one thing the reader must do first. With 8 people at most, everyone reads everything, so do not post routine noise.

Use it from an AI agent#

The same actions are available as seven tools on the Instant Reply MCP server. An agent can check eligibility, create a group and post to it under the same rules.

• whatsapp_groups_eligibility takes no input.
• list_whatsapp_groups takes no input.
• create_whatsapp_group takes a subject and an optional description.
• get_whatsapp_group_invite_link takes a group_id and an optional reset flag.
• send_whatsapp_group_message takes a group_id plus exactly one of text or template.
• remove_whatsapp_group_participants takes a group_id and 1 to 7 participants.
• approve_whatsapp_group_join_requests takes a group_id, an action of approve or reject, and 1 to 7 participants.

What we could not confirm#

• Our create call has no option to turn on join approval. We could not confirm Meta's default for new groups.
• Whether the business number counts toward the 8-person cap is not stated on the Meta pages we read.
• No delivery guarantee. Meta delivers the message and reports its status.

Using an AI agent? See how to connect Claude Code to WhatsApp for updates and approvals.

Troubleshooting#