Skip to main content

WhatsApp groups

Your AI agent can now take part in WhatsApp groups. You create a group from Yellow.ai, invite people to it with an invite-link message, and your AI agent replies inside the group, where every member sees the conversation. Your team can also take over a group chat from the Inbox.

Early access

WhatsApp groups is turned on per AI agent. If you don't see Manage groups on your WhatsApp number, ask your Yellow.ai account team to enable it.

This page explains, step by step, what you need before you start, how to create and run groups, exactly what is and is not allowed, and what to do when something does not work. Please read Limits before you plan anything: a WhatsApp group holds at most 8 people.


1. What you can do​

You canWhere
Create, rename and delete groupsChannels › WhatsApp › Manage groups
Copy or reset a group's invite linkManage groups
Send the invite-link message from a campaignEngage › Outbound › Create campaign (see Option A)
Send the invite-link message from your own systemNotification API (see Option B)
See members, remove a memberManage groups
Approve or decline people who ask to joinManage groups (only for groups that need approval)
Let your AI agent reply inside the groupAutomatic once the group exists
Run a flow when someone joins, leaves, asks to join, or the group changesEvents (see section 9)
Read group conversations and reply as an agentInbox

2. Before you start (all four are required)​

  1. Your WhatsApp number is connected on the WhatsApp Cloud API. Groups do not work on on-premise numbers or on numbers connected through another provider (for example Infobip, Karix or Gupshup). The Manage groups button appears only on Cloud API numbers.
  2. Your number is an Official Business Account (OBA). This is Meta's rule, not Yellow.ai's. Without it, WhatsApp refuses to create groups (error 131215). Check it in WhatsApp Manager › Phone numbers › your number › Profile › Official business account. Meta reviews OBA requests; if you are refused, you can re-apply after 30 days.
  3. Your number is not a coexistence number (a number also used in the WhatsApp Business app) and is not shared with another partner through Meta's Multi-solution Conversations. Meta excludes both from groups.
  4. Group updates are switched on for your account. Yellow.ai turns this on for your WhatsApp setup. If you create a group and it stays in Creating for more than a few minutes, contact Yellow.ai support (see Troubleshooting).

You also need the Admin or Super admin role on the AI agent to see Manage groups.


3. Limits (read this first)​

These limits come from WhatsApp. Yellow.ai cannot raise them.

LimitValueWhat it means for you
People per group8At most 8 people can be in a group. Your business number is the group's creator and admin; WhatsApp lists it separately from the members. Plan for at most 8 people per group.
Groups per business number10,000Delete groups you no longer need.
Businesses per group1Only your number can be the business in the group.
How people joinInvite link onlyYou cannot add someone directly. People join by tapping the group's invite link.
After you remove someoneCannot rejoin with the linkA removed person cannot come back through the invite link.
Group nameUp to 128 characters
Group descriptionUp to 2,048 characters

The 8-person rule, in practice​

If more than 8 people have the same group's link, the first people to tap it join. Everyone after that sees that the group is full and cannot join. You are still charged for every invite message you sent.

So, never send one group's link to more people than it has open seats. Plan your groups like this:

People you want in groupsGroups to createWho gets which link
81People 1–8 → Group 1
162People 1–8 → Group 1, people 9–16 → Group 2
173People 1–8 → Group 1, 9–16 → Group 2, person 17 → Group 3
1001312 groups of 8, and 1 group of 4

Yellow.ai does not split people into groups for you. You create the groups and decide who gets which link.

Manage groups and the campaign's group picker show how many members each group has. Nothing stops you from sending a link to more people than the group has open seats. Extra invites are your choice and your cost.

An invite link works for anyone who has it, not only the people you sent it to. If someone forwards it, a stranger can take a seat. To stop this:

  • Create the group with Who can join: People you approve (see section 5), or
  • Reset the link (Manage groups › Invite link › Reset). The old link stops working at once. People already in the group stay in it.

4. Open Manage groups​

  1. Go to Extensions › Channels › WhatsApp.
  2. On the card of your connected number, click Manage groups.

The WhatsApp groups page opens for that number. On the left is the list of your groups (with 3 of 8 members under each name). On the right are the details of the selected group. To go back, click WhatsApp messenger at the top left.

  • Search groups finds a group by name.
  • Show deleted groups also lists groups you deleted. Deleted groups cannot be used again.
  • Sync from WhatsApp (top right) brings in groups that exist on your number but were not created from this screen.

The page has its own link, including the selected group, so you can bookmark it or share it with a teammate.


5. Create a group​

  1. On the WhatsApp groups page, click Create group (top right).
  2. Fill in:
    • Group name (required, up to 128 characters). Members see this name in WhatsApp.
    • Description (optional, up to 2,048 characters).
    • Who can join:
      • Anyone with the invite link: whoever taps the link joins straight away, until the group is full.
      • People you approve: tapping the link sends you a join request; the person joins only after you approve it (see section 8).
  3. Click Create.

The group shows Creating for a few seconds while WhatsApp sets it up. When it changes to Active, the group has its invite link and is ready.

Who can join cannot be changed from Yellow.ai after the group is created. If you need the other setting, create a new group.


6. Invite people​

People join only through the group's invite link. Yellow.ai sends the invite-link message from Engage only, through a campaign or the Notification API. That way every invite is recorded in Engage reports and charged like any other WhatsApp template message. Manage groups does not send invites.

The message is built from one of Meta's ready-made group invite templates. You put the group's Group ID in the group link variable, and WhatsApp puts the group's current invite link into the message for you.

Step 1: Add an invite template to your WhatsApp account (one time only).

  1. Go to Engage › Templates › Create new template › WhatsApp.
  2. Enter a Template name, choose the Template language, and set Template category to Utility.
  3. Tick Use a WhatsApp group invite template. The body editor is replaced by Meta's ready-made templates for that language, with their text shown read-only and the variable that becomes the group's invite link.
  4. Pick one and click Create template.

In English, Meta's templates are:

TemplateMessage (variables in {{ }})
group_invite_link_conciseYour {{1}} request with {{2}} is confirmed. Please join the WhatsApp group to start: {{3}} Thank you!
group_invite_linkHi {{1}}, your request for {{2}} service from {{3}} was successfully received! You can start the service by clicking and joining the group below. {{4}} Thank you!
group_invite_link_detailedHi {{1}}, We are pleased to inform you that your request for {{2}} from {{3}} has been successfully received. To facilitate your session, we have created a dedicated WhatsApp group. Please join the group using the link below to proceed with your request: {{4}} Thank you for using our service!

Important:

  • Meta reviews the template. Approval can take up to 24 hours. You cannot send it before it is approved.
  • You cannot change the wording. Meta keeps these templates exactly as published so they are priced as utility messages.
  • The template is added to the WhatsApp Business Account of the number you are using.

Step 2: Wait for Meta's approval.

The template appears in Engage › Templates straight away, as Pending, and changes to Approved once Meta approves it. If you added the template somewhere else (for example in WhatsApp Manager), click Sync in Engage › Templates so Engage knows it.

Step 3: Send the invites with Option A or Option B below.

For every invite:

  • It appears in Engage reports with its delivery status (sent, delivered, read, failed).
  • It is a utility template message, charged by Meta like any other utility template.
  • The person must have WhatsApp on that number to receive it.
  • Text values cannot contain new lines, tabs, or 4 or more spaces in a row.

Option A: send invites from a campaign​

Use this when you have a list of people (a segment) to invite into one group.

Before you start, you need steps 1 and 2 above (an approved invite template in Engage) and an active group on the number you send from.

  1. Go to Engage › Outbound › Create campaign, give it a name and choose WhatsApp.
  2. Message template: pick your approved invite template, for example group_invite_link_concise.
  3. In Template details:
    • Sender ID: choose the number that created the group. A group belongs to one number. If you change the number, pick the group again.
    • WhatsApp group: a separate section above Map variables, with a Pick a group list. It shows the sender number's active groups and how many members each has. A full group (8 of 8) cannot be picked. If the number has no active group, the section says so and links to Manage groups. The section names the variable that becomes the link (for example {{3}}; the number depends on the template).
    • Map variables: fill in the text variables as usual. The group link variable is not listed here.
    • The group field can take a few seconds to appear, because Yellow.ai first checks the template with Meta. Next stays disabled until that check finishes.
  4. Target audience: choose a segment with no more people than the group's open seats. Everyone in the campaign gets the same group's link, and only the first people to join get in.
  5. Schedule and launch as usual. Test campaign works too: the test message carries the same group link.

Rules:

  • One group per campaign. To invite 17 people into three groups, create three groups and run three campaigns, each to a segment of up to 8 people (fewer if the group already has members).
  • Group invite templates cannot be used in an A/B test.
  • Sent, delivered, read and failed counts appear in the campaign report like any other campaign.

Option B: send invites with the Notification API​

Use this to send an invite from your own system, for example right after a customer completes a purchase. Everything in the Notification API guide applies (host, API key, reports); a group invite needs two extra details.

  1. Copy the group's ID: Manage groups › select the group › Group ID › Copy.
  2. In the request, put the Group ID in params as the value of the group link variable, and set groupIdParam to the name of that variable.
curl --location 'https://cloud.yellow.ai/api/engagements/notifications/v2/push?bot=<botId>' \
--header 'x-api-key: <your API key>' \
--header 'Content-Type: application/json' \
--data '{
"userDetails": { "number": "919876543210" },
"notification": {
"type": "whatsapp",
"sender": "918068983706",
"templateId": "group_invite_link_concise",
"language": "en",
"params": { "1": "Diwali", "2": "Cadbury", "3": "<Group ID>" },
"groupIdParam": "3"
}
}'
FieldWhat to put
senderThe number that created the group.
templateIdYour approved invite template.
paramsA value for every variable. The group link variable takes the Group ID, not a link: WhatsApp builds the link.
groupIdParamThe name of the group link variable: 3 for group_invite_link_concise, 4 for group_invite_link and group_invite_link_detailed.

The API checks the request before sending: it answers 400 if groupIdParam is not a variable in the template body, if its value is missing or empty, or if the template is a carousel or a direct (non-template) message. Use /v2/push; /v2/push-carousel does not support group invites.

Copy the link (Manage groups › Invite link › Copy) and share it however you like. Yellow.ai does not track links shared this way, and the 8-person limit still applies.


7. Manage a group​

Select a group in Manage groups. The top shows the group name, its status, who can join and when it was created, plus three numbers: Members (out of 8), Open seats, and Join requests.

ToDo thisGood to know
Rename it or change the description⋮ › EditMembers see the new name in WhatsApp.
Get the latest member list from WhatsApp⋮ › RefreshYellow.ai also updates members automatically when people join or leave.
Copy the invite linkInvite link › Copy
Stop an old link from workingInvite link › ResetThe old link stops at once. Members stay. Share the new link.
Remove a memberMembers › ⋮ next to the number › RemoveThey are removed for good: they cannot rejoin with the invite link.
Delete the group⋮ › DeleteCannot be undone. Everyone, including your number, leaves and the group closes. Your AI agent can no longer message it.

Group statuses:

StatusMeaning
ActiveReady to use.
CreatingWhatsApp is still setting it up (usually a few seconds).
SuspendedWhatsApp has suspended the group. Messages cannot be sent to it.
FailedWhatsApp could not create it. Try again; check the prerequisites.
DeletedThe group was deleted. It only shows when Show deleted groups is ticked.

8. Approve or decline join requests​

Only for groups created with Who can join: People you approve.

  1. Select the group. The Join requests section lists everyone who asked to join.
  2. Click Approve or Decline for each person.
  3. Check WhatsApp reloads the list straight from WhatsApp if you think it is out of date.

When the group already has 8 members, approving is turned off: there are no seats left.


9. Group events for your flows​

Yellow.ai turns WhatsApp's group updates into events that can start a flow. They are off by default. Switch on the ones you need in your AI agent's Events settings (search for whatsapp-group).

Switch them on from the Development environment (use the environment switcher at the top). The live environment refuses changes to events with Forbidden. The setting still applies to your live AI agent straight away; no publish is needed.

EventWhen it fires
whatsapp-group-createdWhatsApp finished creating a group
whatsapp-group-participant-joinedSomeone joined (by link, or after you approved them)
whatsapp-group-participant-leftSomeone left, or you removed them
whatsapp-group-join-requestSomeone asked to join, or withdrew their request
whatsapp-group-updatedThe name, description or photo changed, a change failed, or WhatsApp suspended the group
whatsapp-group-deletedThe group was deleted

The flow runs inside the group's conversation, so anything the flow sends goes to the whole group (for example, a welcome message when someone joins).


10. How your AI agent behaves in a group​

  • One group = one conversation. The group has a single chat, a single history and a single flow position, shared by all members. The conversation is named after the group.
  • Your AI agent receives every message in the group and can reply to each one. There is no "reply only when mentioned" setting today. Design your flows for a group: short replies, and expect several people to talk at once.
  • Replies go to the whole group. Every member sees every reply. Do not send anything meant for one person only.
  • Who said what: each incoming message carries the sender's details (phone number and WhatsApp name, and username when the person uses one). Flows can read it from the message's channel details (groupParticipant).
  • Buttons and lists become numbered options. WhatsApp does not allow buttons or lists in groups. Yellow.ai sends them as numbered text, for example 1. Yes / 2. No. When a member replies 2, your AI agent receives the second option. Images or headers attached to such a message are not sent.
  • What can be sent to a group: text, images, videos, documents and audio, and text or media templates.
  • What cannot: buttons and lists (converted as above), authentication templates, calls, view-once and disappearing messages, and editing or deleting a message after it is sent.
  • The 24-hour rule applies to the group. You can send normal messages only if any member wrote in the group in the last 24 hours. Outside that window, WhatsApp accepts templates only.

11. Groups in the Inbox​

  • A group appears as one conversation named after the group.
  • Every member's message is labelled with their name and number (or username when they have no number).
  • WhatsApp-style lines show what happened in the group: Group created, Asha joined using the invite link, Bala left, +91… was removed, Group renamed to "…", Group suspended by WhatsApp, and so on. They show in Bot messages A line is saved only for the events you switched on in section 9; for example, switch on whatsapp-group-participant-joined and whatsapp-group-participant-left to see who joined and left.
  • An agent can take over the group like any chat. The agent's replies go to the whole group.
  • When replying, an agent can type @ to pick a member who has written in the group; their name is added to the reply. WhatsApp does not support real mentions from businesses, so it arrives as plain text and does not notify that member separately.

12. Billing​

Meta charges for WhatsApp groups. The prices are Meta's, not Yellow.ai's:

  • Messages to a group are charged for each member who receives them: a message to a group of 6 is charged as up to 6 messages. Meta uses the categories group_service, group_utility and group_marketing.
  • Invite messages are utility templates sent to individual people and are charged per message, whether or not the person joins.
  • Utility templates sent inside an open group window are also charged.

See WhatsApp pricing for how Yellow.ai bills WhatsApp messages.


13. Troubleshooting​

What you seeWhyWhat to do
No Manage groups buttonThe number is not on the Cloud API, or you are not an AdminUse a Cloud API number; ask an admin.
"Create group failed … 131215"The number is not an Official Business AccountApply for OBA in WhatsApp Manager (section 2).
Group stays CreatingWhatsApp has not confirmed it to Yellow.aiWait a minute and refresh. If it persists, contact Yellow.ai support.
The invite template is not in the campaign's template listIt is not approved yet, or it was added outside Engage and not syncedWait for approval (up to 24 hours). If you added it in WhatsApp Manager, click Sync in Engage › Templates (section 6).
No Use a WhatsApp group invite template optionThe template category is not UtilitySet Template category to Utility.
An invite failed for one numberThe number is wrong, has no WhatsApp, or the value text broke WhatsApp's rulesCheck the number has the country code; remove new lines from values. The reason is in the campaign or Notification API report.
An invite failed with "(#100) Invalid parameter … Failed to get group invite link"The Group ID is wrong, the group was deleted, or it belongs to a different number than the senderCopy the Group ID again from Manage groups and send from the number that created the group.
The campaign drawer shows a normal "Map variable" for the group linkThe sender number's WhatsApp account has no approved invite template with that name, or the check with Meta failedWait a few seconds, check the template is approved and synced, or choose the sender number again.
"WhatsApp group invite templates can't be used in an A/B test"A/B tests are not supported for group invitesUse a single-template campaign.
Someone says the group is fullThe group already has 8 membersCreate another group and send that link instead.
A removed person cannot rejoinWhatsApp blocks rejoining by link after removalThis cannot be undone. Use a different group if needed.
The AI agent did not reply in the groupNo member wrote in the last 24 hours, or the group is suspendedSend a template, or check the group status.
Members see numbered options instead of buttonsWhatsApp does not allow buttons in groupsExpected. Members reply with the number.
The Inbox chat list still shows the old group nameThe chat list keeps the name from the first messageThe open chat's header shows the current name.
Join/leave lines are missing in My chatsToday they show in Bot messages onlyOpen the conversation from Bot messages.

14. Not available yet​

Plan around these. They are not supported today:

  • Splitting a list of people into groups of 8 automatically. Create the groups yourself and send each one its own invite (Option A).
  • Sending invites from flows, or choosing a different group per person in a campaign. Use the Notification API for per-person groups (Option B).
  • Using a group invite template in an A/B test campaign.
  • Adding someone to a group directly (WhatsApp allows joining by link only).
  • Changing Who can join after a group is created.
  • Automatically approving join requests while seats are free.
  • Making the AI agent reply only when it is mentioned or called by name.
  • Changing the group photo from Yellow.ai.
  • Groups on numbers that are not on the WhatsApp Cloud API.