Manage WhatsApp groups

What it is

The YCloud WhatsApp Groups API lets your business create invitation-only WhatsApp groups. You send an invite link to each person, and that person chooses whether to join. If the group requires approval, you can review the person’s join request before allowing them into the group. This guide covers group setup, management, and outbound group messages. Group conversations do not appear in Inbox.

Before you begin

Before you integrate, make sure your WhatsApp business phone number meets these requirements:

The business has an Official Business Account (OBA).
The phone number uses the WhatsApp Cloud API, not the WhatsApp Business App.
The phone number does not use Multi-solution Conversations.
Your YCloud account has access to the phone number.
You have a public HTTPS URL where YCloud can send webhook events.
Before sending invite links through a template message, you have an approved group invite template.

YCloud manages the required WhatsApp platform subscriptions. You only need to configure a YCloud webhook endpoint and select the YCloud group events that you want to receive.

YCloud and WhatsApp check whether the phone number is eligible. If it is not, verify its OBA status, Cloud API setup, and access in YCloud.

Supported capabilities and limits

YCloud currently supports:

Creating, listing, retrieving, and deleting groups.
Retrieving and resetting invite links.
Sending an approved invite-link template to an individual WhatsApp user.
Listing, approving, and rejecting join requests.
Removing participants.
Updating the group subject and description.
Updating the group profile picture with a JPEG file.
Sending text, media, sticker, and supported template messages to a group.
Receiving group lifecycle, participant, settings, and suspension webhooks.

The WhatsApp platform applies these limits:

A group can have up to 8 participants.
A business phone number can create up to 10,000 groups.
A group can contain only one Cloud API business phone number.
A single YCloud request can remove up to 8 participants.
A group subject can contain up to 128 characters.
A group description can contain up to 2,048 characters.

These APIs do not support pinning or unpinning messages.

How it works

Choose which group events YCloud should send to your webhook endpoint.
Send a request to create a group. YCloud immediately returns a requestId.
Wait for the lifecycle webhook that reports whether creation succeeded.
If creation succeeds, save the returned groupId and invite link. Store and use the groupId exactly as YCloud returns it.
Send the invite link to one person at a time.
If the group requires approval, approve or reject each join request.
Use participant events and the retrieve-group API to keep your member list up to date.
Use webhook events to confirm group deletion, participant removal, and settings changes.

A 200 response with status: "pending" only means that YCloud received the request. The operation finishes later. Use the matching webhook event to find out whether it succeeded.

Configure webhooks

Subscribe your YCloud webhook endpoint to these events before creating a group:

Event	Use it for
`whatsapp.group.lifecycle_update`	Group creation and deletion results.
`whatsapp.group.participants_update`	Joins, join requests, removals, departures, and participant-level failures.
`whatsapp.group.settings_update`	Subject and description update results.
`whatsapp.group.status_update`	Group suspension and suspension-clear events.

When YCloud sends an event, verify YCloud-Signature, save the event, and return a 2xx response promptly. You can then process it in the background. YCloud can send the same event more than once, and different events might arrive out of order. Use the event id to recognize a delivery that you have already handled. For an operation started through the API, match the webhook to the original request by requestId. Actions started by a participant, such as joining or leaving, might not include a requestId. In that case, use the event type, groupId, participant identifier, and event time.

Create a group

Choose the join approval mode:

Mode	Behavior
`auto_approve`	A user can join directly through the invite link. This is the default.
`approval_required`	A user submits a join request that you must approve before they join.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "New purchase inquiry",
    "description": "Discuss purchase requirements with our team.",
    "joinApprovalMode": "approval_required"
  }'

Group creation finishes asynchronously. The first response only confirms that YCloud received the request:

{
  "requestId": "REQ_1",
  "status": "pending"
}

Wait for whatsapp.group.lifecycle_update. A successful group_create event contains the final groupId and inviteLink.

{
  "id": "evt_group_lifecycle_123",
  "type": "whatsapp.group.lifecycle_update",
  "whatsappGroup": {
    "type": "group_create",
    "requestId": "REQ_1",
    "status": "created",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK"
  }
}

Save and use groupId exactly as it appears in the successful event. It is case-sensitive. Do not decode, modify, or generate it yourself.

Invite participants

You can use the invite link from the creation webhook or retrieve it later with the invite-link endpoint. Reset the link only when you need every previously shared link to stop working. After a reset, people cannot join with the old link. To send the link through WhatsApp, first prepare an approved invite template. Then send that template to an individual user:

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups/inviteLink/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315552222",
    "templateName": "group_invite_link",
    "languageCode": "en_US",
    "parameters": [
      {
        "type": "group_id",
        "group_id": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE"
      }
    ]
  }'

This endpoint sends a template message to the person specified by to or recipient. It does not send a message to the group. If you provide both fields, YCloud uses to.

Handle join requests

For an auto_approve group, wait for a participant-added webhook before recording the user as a member. For an approval_required group:

Receive group_join_request_created, or retrieve the pending requests.
Save the joinRequestId while the request is still pending.
Send each ID to the approve or reject endpoint.
Check both successful and failed items in the response, including failedJoinRequests and errors.
Confirm that the person joined by using the participant-added webhook or by retrieving the group.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups/GROUP_ID/joinRequests/approve \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "joinRequests": ["join-request-id"]
  }'

A user can revoke a pending request. If an approval fails because the request no longer exists, refresh the pending request list instead of retrying the same ID indefinitely.

List groups and join requests

The group list and join-request list return results in pages. A cursor is a temporary value that marks your position in the list. limit controls the page size, ranges from 1 to 1024, and defaults to 25. Pass after for the next page or before for the previous page.

curl --get \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "after=NEXT_CURSOR"

Do not save a cursor as a permanent ID. If it is invalid or expired, start again from the first page.

Send a group message

Use POST /whatsapp/groupMessages/sendDirectly to send one message to the group’s current members. YCloud retrieves the group first and fixes the recipient snapshot for that message. If the group has eight participants including the business sender, YCloud creates seven member results. People who join later do not receive the earlier message and are not added to its history. The send response confirms acceptance. Use GET /whatsapp/groupMessages/{id} to retrieve the group-level result, each member’s delivery status, and final pricing. The group-level status describes the overall send result: accepted by YCloud, sent by Meta, or failed. Each item in recipients describes one member and can have a different status. YCloud supports text, image, video, audio, document, sticker, and supported template messages. Authentication templates and templates with interactive or commerce components are rejected. For marketing templates, YCloud can use the MM Lite channel when the WABA is eligible and at least one recipient has an MM Lite price. Member records then use group_marketing_lite. Utility and service messages keep group_utility and group_service and do not use MM Lite. If a member has no price for the selected channel, YCloud still submits the group when at least one member can be sent. It does not freeze an estimated amount for the missing-price member and does not fall back to the other channel’s price. Final billing uses the price reported by the delivery result.

Maintain a group

Remove participants

You can remove up to eight participants in one request. Remove duplicate participant identifiers before sending it. Some participants might be removed while others fail, so check removedParticipants, failedParticipants[].errors, and the top-level errors in the participant webhook.

Update settings

You can update subject, description, a JPEG profile_picture_file, or any combination of these settings. Send JSON when changing text only. Send multipart/form-data when uploading a profile picture. The initial response only confirms that YCloud accepted the request. Wait for the settings webhook and check every settings[] entry to see what was actually updated.

Delete a group

The initial delete response does not confirm that the group was deleted. Wait for a lifecycle webhook with type: "group_delete" and a final status. After deletion, the group cannot be used again. Events that were already in progress might still arrive.

Handle asynchronous results safely

Store the requestId, the requested operation, and your own reference ID together.
If you receive the same event id again, do not apply the same change twice.
Make sure that processing the same event again does not create duplicate data or side effects.
Expect events to be repeated or arrive out of order.
Retrieve the group again when an event conflicts with your current data.
Check top-level and item-level errors for partial operations.
Redact API keys, invite links, participant identifiers, and personal data from general application logs.

Errors and troubleshooting

An API request can fail immediately or after YCloud has accepted it:

For an immediate failure, check the standard YCloud error response. The top-level error.code is a general YCloud code such as BAD_REQUEST or FORBIDDEN. error.whatsappApiError can contain additional details from WhatsApp. Do not decide what your application should do by matching the human-readable message text.
For a failure reported later, check the group webhook. Depending on the operation, review whatsappGroup.errors, failedParticipants[].errors, or settings[].errors.

Scenario	Recommended action
Group not found or unavailable	Verify that the `groupId` is exactly the value returned by YCloud, then retrieve the latest group state.
Cursor invalid or expired	Restart pagination from the first page.
Operation partially succeeded	Process successful and failed items separately.
Duplicate participants	Remove duplicate participant IDs before retrying.
Group participant limit reached	Stop adding participants and report that the group is full.
Group suspended	Wait for a status update or contact support.
Group operations rate-limited	Retry with exponential backoff, jitter, and bounded attempts.
Phone-number group limit reached	Remove unused groups or contact support.
Participant not in the group	Refresh membership instead of repeating the removal.
Join request not found	Refresh pending requests; it might have been revoked or processed.
Group creation temporarily restricted	Stop creating groups and review the recent messaging strategy.
Phone number not eligible	Verify OBA status, Cloud API onboarding, and YCloud access.

Common invite-link failures also include a reset or expired link, a full group, or a user who was previously removed by the business. Do not retry unchanged requests indefinitely.

End-to-end checklist

Before going live, use an eligible test phone number to complete this full flow:

Subscribe a test webhook endpoint to all four group event types.
Create an approval_required group and store the returned requestId.
Wait for the matching group_create event and store its groupId and inviteLink.
Send the approved invite template to a test user.
Have the user submit a join request.
Receive or list the request, then approve its joinRequestId.
Wait for the participant-added event.
Retrieve the group and confirm that the participant is present.
Remove the test participant and confirm the asynchronous result.
Delete the test group and confirm the lifecycle event.

The examples in this guide follow the current YCloud API contract. Complete this checklist successfully before using the integration in production.

API reference

Operation	Reference
Create a group	API reference
List groups	API reference
Retrieve a group	API reference
Delete a group	API reference
Retrieve an invite link	API reference
Reset an invite link	API reference
Send an invite-link message	API reference
List join requests	API reference
Approve join requests	API reference
Reject join requests	API reference
Remove participants	API reference
Update group settings	API reference
Send a group message directly	API reference
Retrieve a group message	API reference

Webhook examples

Lifecycle events

Handle group creation and deletion results.

Participant events

Handle joins, join requests, removals, and participant-level failures.

Settings events

Handle subject and description update results.

Status events

Handle group suspension and suspension-clear events.

Getting Started

Guides

Endpoints

Webhooks

Manage WhatsApp groups

What it is

Before you begin

Supported capabilities and limits

How it works

Configure webhooks

Create a group

Invite participants

Handle join requests

List groups and join requests

Send a group message

Maintain a group

Remove participants

Update settings

Delete a group

Handle asynchronous results safely

Errors and troubleshooting

End-to-end checklist

API reference

Webhook examples

Lifecycle events

Participant events

Settings events

Status events

​What it is

​Before you begin

​Supported capabilities and limits

​How it works

​Configure webhooks

​Create a group

​Invite participants

​Handle join requests

​List groups and join requests

​Send a group message

​Maintain a group

​Remove participants

​Update settings

​Delete a group

​Handle asynchronous results safely

​Errors and troubleshooting

​End-to-end checklist

​API reference

​Webhook examples

Lifecycle events

Participant events

Settings events

Status events

What it is

Before you begin

Supported capabilities and limits

How it works

Configure webhooks

Create a group

Invite participants

Handle join requests

List groups and join requests

Send a group message

Maintain a group

Remove participants

Update settings

Delete a group

Handle asynchronous results safely

Errors and troubleshooting

End-to-end checklist

API reference

Webhook examples