Create WhatsApp groups and message them from code.

Before you start

Meta sets three conditions. If one fails, create calls return a 422 with the code GROUPS_INELIGIBLE.

1. Your WhatsApp number is connected to Instant Reply. WhatsApp numbers come with Growth and Pro.
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.

Ask the API instead of guessing. The eligibility call returns eligible, and when it is false, one reason: not_connected, coexistence, not_official_business_account or check_failed.

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

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

You also need an API key. Every paid plan includes the REST API. The API reference covers keys and scopes.

Create a group and send a message

The base URL is https://api.instantreply.co/v1. Create a group first. Keep the group_id and share the invite_link.

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://..."}

Then send to the group. Pass either text or template, not both. A group id that does not belong to your number returns 404 with GROUP_NOT_FOUND.

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."}'

# Send an approved template instead of text:
# -d '{"template": {"name": "alert_notice", "language": "en"}}'

A missing or too long subject returns 400. Each group id is checked against your own number before any read, change or send.

All group endpoints

Reads need the scope conversations:read. Writes need messages:send.

MCP tools for agents

The same actions are available as seven tools on the Instant Reply MCP server. An agent can check eligibility, make a group and post to it. Send needs exactly one of text or template.

• whatsapp_groups_eligibility (no input)
• list_whatsapp_groups (no input)
• create_whatsapp_group (subject, description (optional))
• get_whatsapp_group_invite_link (group_id, reset (optional))
• send_whatsapp_group_message (group_id, plus either text or template)
• remove_whatsapp_group_participants (group_id, participants (1 to 7))
• approve_whatsapp_group_join_requests (group_id, action (approve or reject), participants (1 to 7))

Limits

Meta sets the first five. The other rows are ours. Meta can change its limits, so check Meta's Groups API page before you plan around a number.

Cost. Meta bills group messages in its own groups categories, and the rates are on Meta's Groups API pricing page. We list no rates here. Instant Reply adds no fee on top of Meta's.

Example: an alerts group for your team

A shop owner wants one place where the team sees three things: a subscription that is about to end, an angry customer, and a hot lead. Your code decides when each one happens. The API only creates the group and posts the message.

1. Call the eligibility endpoint once. Stop here if it says false and fix the reason.
2. Create the group with the subject "Alerts". Store the returned 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 with the send endpoint.
5. When someone leaves the team, remove their number. You can also reset the invite link.

The same pattern fits a client group, a support group, or a team room. Keep in mind that a group holds 8 people at most, and you count as one.

No code needed? Owners and admins can do the same in Settings, Account. You see your groups, copy an invite link, turn alerts on for one group, or start a new group from the Alerts, Team, Clients and Support quick picks. The controls show only when your number is eligible.

What this does not do

• It does not add people. They join from the invite link, and Meta allows no other way.
• It does not send buttons. Meta does not support interactive messages in groups.
• It does not send media. The API accepts text and approved templates only.
• It does not promise delivery. Meta delivers the message and reports its status.
• It does not work for numbers without the verified badge, or numbers that also run in the WhatsApp Business app.
• Our create call has no option to turn on join approval, and we could not confirm Meta's default for new groups.

For the wider setup, see WhatsApp Business API with Instant Reply and the full WhatsApp Groups API guide.