WhatsApp groups
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.
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.
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 can | Where |
|---|---|
| Create, rename and delete groups | Extensions › Channels › Messaging › WhatsApp › Manage groups |
| Copy or reset a group's invite link | Manage groups |
| Send the invite-link message from a campaign | Engage › Outbound › Create campaign (see Option A) |
| Send the invite-link message from your own system | Notification API (see Option B) |
| See members, remove a member | Manage groups |
| Approve or decline people who ask to join | Manage groups (only for groups that need approval) |
| Let your AI agent reply inside the group | Automatic once the group exists |
| Run a flow when someone joins, leaves, asks to join, or the group changes | Events (see section 9) |
| Read group conversations and reply as an agent | Inbox |
2. Before you start (all four are required)
- 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.
- 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. - 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.
- 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.
| Limit | Value | What it means for you |
|---|---|---|
| People per group | 8 | At 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 number | 10,000 | Delete groups you no longer need. |
| Businesses per group | 1 | Only your number can be the business in the group. |
| How people join | Invite link only | You cannot add someone directly. People join by tapping the group's invite link. |
| After you remove someone | Cannot rejoin with the link | A removed person cannot come back through the invite link. |
| Group name | Up to 128 characters | |
| Group description | Up 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 groups | Groups to create | Who gets which link |
|---|---|---|
| 8 | 1 | People 1–8 → Group 1 |
| 16 | 2 | People 1–8 → Group 1, people 9–16 → Group 2 |
| 17 | 3 | People 1–8 → Group 1, 9–16 → Group 2, person 17 → Group 3 |
| 100 | 13 | 12 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.
Links can be forwarded
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
- Go to Extensions › Channels › Messaging › WhatsApp.
- On the card of your connected number, click Manage groups.
A panel opens. 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.
- Search groups finds a group by name.
- Show deleted groups also lists groups you deleted. Deleted groups cannot be used again.
- The refresh button next to the search box (Sync from WhatsApp) brings in groups that exist on your number but were not created from this screen.
5. Create a group
- In Manage groups, click Create group.
- 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).
- 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).
- Go to Engage › Templates › Create new template › WhatsApp.
- Enter a Template name, choose the Template language, and set Template category to Utility.
- 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.
- Pick one and click Create template.
In English, Meta's templates are:
| Template | Message (variables in {{ }}) |
|---|---|
group_invite_link_concise | Your {{1}} request with {{2}} is confirmed. Please join the WhatsApp group to start: {{3}} Thank you! |
group_invite_link | Hi {{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_detailed | Hi {{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.
- Go to Engage › Outbound › Create campaign, give it a name and choose WhatsApp.
- Message template: pick your approved invite template, for example
group_invite_link_concise. - 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.
- Map variables: fill in the text variables as usual. The group link variable shows as
{{3}}· WhatsApp group (the number depends on the template) with a Pick a group list. The list shows this 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 drawer says so and links to Manage groups. - 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.
- 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.
- 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.
- Copy the group's ID: Manage groups › select the group › Group ID › Copy.
- In the request, put the Group ID in
paramsas the value of the group link variable, and setgroupIdParamto 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"
}
}'
| Field | What to put |
|---|---|
sender | The number that created the group. |
templateId | Your approved invite template. |
params | A value for every variable. The group link variable takes the Group ID, not a link: WhatsApp builds the link. |
groupIdParam | The 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.
Option C: share the link yourself
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.
| To | Do this | Good to know |
|---|---|---|
| Rename it or change the description | ⋮ › Edit | Members see the new name in WhatsApp. |
| Get the latest member list from WhatsApp | ⋮ › Refresh | Yellow.ai also updates members automatically when people join or leave. |
| Copy the invite link | Invite link › Copy | |
| Stop an old link from working | Invite link › Reset | The old link stops at once. Members stay. Share the new link. |
| Remove a member | Members › ⋮ next to the number › Remove | They are removed for good: they cannot rejoin with the invite link. |
| Delete the group | ⋮ › Delete | Cannot be undone. Everyone, including your number, leaves and the group closes. Your AI agent can no longer message it. |
Group statuses:
| Status | Meaning |
|---|---|
| Active | Ready to use. |
| Creating | WhatsApp is still setting it up (usually a few seconds). |
| Suspended | WhatsApp has suspended the group. Messages cannot be sent to it. |
| Failed | WhatsApp could not create it. Try again; check the prerequisites. |
| Deleted | The 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.
- Select the group. The Join requests section lists everyone who asked to join.
- Click Approve or Decline for each person.
- 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.
| Event | When it fires |
|---|---|
whatsapp-group-created | WhatsApp finished creating a group |
whatsapp-group-participant-joined | Someone joined (by link, or after you approved them) |
whatsapp-group-participant-left | Someone left, or you removed them |
whatsapp-group-join-request | Someone asked to join, or withdrew their request |
whatsapp-group-updated | The name, description or photo changed, a change failed, or WhatsApp suspended the group |
whatsapp-group-deleted | The 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 replies2, 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-joinedandwhatsapp-group-participant-leftto 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_utilityandgroup_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 see | Why | What to do |
|---|---|---|
| No Manage groups button | The number is not on the Cloud API, or you are not an Admin | Use a Cloud API number; ask an admin. |
| "Create group failed … 131215" | The number is not an Official Business Account | Apply for OBA in WhatsApp Manager (section 2). |
| Group stays Creating | WhatsApp has not confirmed it to Yellow.ai | Wait a minute and refresh. If it persists, contact Yellow.ai support. |
| The invite template is not in the campaign's template list | It is not approved yet, or it was added outside Engage and not synced | Wait 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 option | The template category is not Utility | Set Template category to Utility. |
| An invite failed for one number | The number is wrong, has no WhatsApp, or the value text broke WhatsApp's rules | Check 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 sender | Copy 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 link | The sender number's WhatsApp account has no approved invite template with that name, or the check with Meta failed | Wait 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 invites | Use a single-template campaign. |
| Someone says the group is full | The group already has 8 members | Create another group and send that link instead. |
| A removed person cannot rejoin | WhatsApp blocks rejoining by link after removal | This cannot be undone. Use a different group if needed. |
| The AI agent did not reply in the group | No member wrote in the last 24 hours, or the group is suspended | Send a template, or check the group status. |
| Members see numbered options instead of buttons | WhatsApp does not allow buttons in groups | Expected. Members reply with the number. |
| The Inbox chat list still shows the old group name | The chat list keeps the name from the first message | The open chat's header shows the current name. |
| Join/leave lines are missing in My chats | Today they show in Bot messages only | Open 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.