> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Manage WhatsApp groups > Learn how to create invitation-only WhatsApp groups, invite people, review join requests, and manage group settings. ## 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](/en/api-reference/guides/api-fundamentals/configure-webhooks) 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 1. Choose which group events YCloud should send to your webhook endpoint. 2. Send a request to create a group. YCloud immediately returns a `requestId`. 3. Wait for the lifecycle webhook that reports whether creation succeeded. 4. If creation succeeds, save the returned `groupId` and invite link. Store and use the `groupId` exactly as YCloud returns it. 5. Send the invite link to one person at a time. 6. If the group requires approval, approve or reject each join request. 7. Use participant events and the retrieve-group API to keep your member list up to date. 8. 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. | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "requestId": "REQ_1", "status": "pending" } ``` Wait for `whatsapp.group.lifecycle_update`. A successful `group_create` event contains the final `groupId` and `inviteLink`. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: 1. Receive `group_join_request_created`, or retrieve the pending requests. 2. Save the `joinRequestId` while the request is still pending. 3. Send each ID to the approve or reject endpoint. 4. Check both successful and failed items in the response, including `failedJoinRequests` and `errors`. 5. Confirm that the person joined by using the participant-added webhook or by retrieving the group. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: 1. Subscribe a test webhook endpoint to all four group event types. 2. Create an `approval_required` group and store the returned `requestId`. 3. Wait for the matching `group_create` event and store its `groupId` and `inviteLink`. 4. Send the approved invite template to a test user. 5. Have the user submit a join request. 6. Receive or list the request, then approve its `joinRequestId`. 7. Wait for the participant-added event. 8. Retrieve the group and confirm that the participant is present. 9. Remove the test participant and confirm the asynchronous result. 10. 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](/api-reference/whatsapp-groups/create-a-group) | | List groups | [API reference](/api-reference/whatsapp-groups/list-groups) | | Retrieve a group | [API reference](/api-reference/whatsapp-groups/retrieve-a-group) | | Delete a group | [API reference](/api-reference/whatsapp-groups/delete-a-group) | | Retrieve an invite link | [API reference](/api-reference/whatsapp-groups/retrieve-a-group-invite-link) | | Reset an invite link | [API reference](/api-reference/whatsapp-groups/reset-a-group-invite-link) | | Send an invite-link message | [API reference](/api-reference/whatsapp-groups/send-a-group-invite-link-message) | | List join requests | [API reference](/api-reference/whatsapp-groups/list-group-join-requests) | | Approve join requests | [API reference](/api-reference/whatsapp-groups/approve-group-join-requests) | | Reject join requests | [API reference](/api-reference/whatsapp-groups/reject-group-join-requests) | | Remove participants | [API reference](/api-reference/whatsapp-groups/remove-group-participants) | | Update group settings | [API reference](/api-reference/whatsapp-groups/update-group-settings) | | Send a group message directly | [API reference](/api-reference/whatsapp-group-messages/send-a-group-message-directly) | | Retrieve a group message | [API reference](/api-reference/whatsapp-group-messages/retrieve-a-group-message) | ## Webhook examples Handle group creation and deletion results. Handle joins, join requests, removals, and participant-level failures. Handle subject and description update results. Handle group suspension and suspension-clear events. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.