Groups

Remove participants

Remove one or more participants from the group.

POST
https://api.wawp.net/v2/groups/{id}/participants/remove?access_token=123456789&id=1234567890%40g.us&instance_id=123456789&participants=%5B%7B%22id%22%3A%221234567890%40c.us%22%7D%5D

Authentication Required

Login to swap the placeholders with your real Instance ID and Access Token.

Log In
Test /v2/groups/{id}/participants/remove endpoint
POST
POST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Log the reason for removal in your internal system.

  • Send a warning message to the user before removing them if applicable.

  • Remove the user from your local database mapping as well.

Pruning the State: The Strategic Governance of Participant Removal

In the lifecycle of a managed community, the ability to selectively withdraw access is as critical as the ability to grant it. The Remove Participants endpoint is your primary tool for Structural Governance and Security Enforcement. It allows you to programmatically prune the membership list of a group, ensuring that only actively relevant stakeholders maintain access to the shared conversational state. By moving participant removal from a manual agent task to an automated business rule, you ensure that "Community Drift" is minimized and that your business remains in absolute control of its collaborative boundaries.

Effective membership management requires a perspective that balances Security, Professionalism, and Operational Efficiency. This guide explores the architectural imperatives of governed participant removal.

🏗️ Architectural Philosophy: The Enforcement of State Boundaries

From a technical perspective, removing a participant is a Revocation of Authorization. You are severing the link between a specific JID and the persistent group context.

Key Architectural Objectives:

  • Irrevocable Withdrawal of Context: Once a participant is removed, they instantly lose access to the group's "Pulse." While they may retain a cached history of previous messages on their local device, they can no longer see new messages, view updated metadata, or see the current participant list. This "Instant Blackout" is essential for protecting sensitive business information when a project ends or a stakeholder's role changes.
  • The Power of Admin Rights: Removal is an "Executive Power." To successfully execute this call, your Wawp instance must be a Group Admin. This ensures that the dismantling of a community's population is a governed act performed by an authorized authority. If your instance is a regular member, the operation will fail with a 403 Forbidden error, preventing unauthorized users from "Self-Moderating" the group.
  • System-Generated Accountability: Every removal triggers a system notification in the chat (e.g., "Business Name removed [User]"). This creates a transparent audit trail for the remaining members, signaling that the community is actively managed and that standards are being enforced.

🚀 Strategic Use Cases: Workflow Transitions and Rotation

The Remove Participants endpoint should be integrated into your broader business logic to handle transitions between different phases of a relationship.

1. Shift Rotation & Handover Management

In global 24/7 support operations, groups often serve as the bridge between time zones. As a support specialist in Asia completes their shift, your system can automatically Remove them from the group while simultaneously adding their counterpart in Europe. This keeps the "Headcount" of the group low and ensures that the customer is only interacting with the team currently on duty, reducing confusion and preventing "Off-hours" messages from reaching sleeping agents.

2. The "Resolved Ticket" Pruning Protocol

For technical troubleshooting groups, once a bug is confirmed as "Resolved" in your CRM, the system should automatically remove all secondary technical experts (senior engineers, developers) while leaving only the account manager and the customer. This "Pruning" focuses the conversation on the final closure steps and prevents technical staff from being distracted by the social "Thank you" messages that follow a successful fix.

3. Subscription & Access Expiry

If your business manages "Premium Community Groups" for paid members, the Remove Participants endpoint is your Subscription Enforcer. When a user's subscription expires in your database, the system triggers the removal call. This turns the WhatsApp group into an "Access-Controlled Asset" that is perfectly synchronized with your billing engine.

🔐 Security & Compliance: Revoking Access in Regulated Environments

In industries like Finance, Healthcare, and Legal Services, controlling who has access to a shared conversation is a regulatory mandate.

The "Need-to-Know" Enforcement

The Remove Participants endpoint allows your system to enforce the principle of "Least Privilege." If a staff member leaves your organization or is moved to a different department, your system can perform a "Global Access Wipe"—scanning all active WhatsApp groups and removing that individual's JID from every shared state. This ensures that no former employee retains a "Backdoor" into ongoing customer conversations via their personal WhatsApp device.

Preventing "Community Creep"

As a group matures, it is common for the membership list to grow stale. The Get Group Info endpoint should be used to periodically audit the population. If a user has not interacted with the group for 30 days and is not a core stakeholder, your system can proactively remove them to maintain a "High-Quality, High-Engagement" environment.

🛡️ Operational Hygiene and Professionalism

Removing a user is a socially sensitive act. Your system should handle it with the same level of care as a welcome sequence.

  • The "Exit Notice" Pattern: Before executing a hard removal, we recommend sending a polite automated message to the group or a 1:1 message to the user explaining why they are being removed (e.g., "Our project is now complete, so we are closing out the active working group. Thank you for your collaboration!"). This prevents the "Kicked out" feeling and maintains your brand's professional reputation.
  • Rate Management: Like adding participants, removing them in bulk should be staggered. Removing 100 users in a single second can trigger security flags. Aim for a "Drip Removal" of 5-10 users per minute to ensure system stability and account safety.

⚙️ Engineering Best Practices: Validation and Resilience

  1. Verify Member Status Before Removal: To avoid unnecessary API calls, use the Get Group Info endpoint to verify that the target JID is actually a member of the group. Attempting to remove someone who isn't there will return an error that could have been avoided with a simple pre-flight check.
  2. Handle Creator Immunity: Remember that the Creator of a group cannot be removed by any other admin. If your system attempts to remove the creator (e.g., your primary instance), the operation will fail at the network level. Your logic should always respect this "Immunity" to prevent deadlocks in your automation.
  3. Event-Driven Synchronization: Ensure your backend listens for the group.participants.update webhook. When a removal is confirmed by the WhatsApp network, your system should update its internal membership cache to ensure that your agent dashboard always displays the accurate population of the room.

🎯 Conclusion: Mastering the Art of the Governed Exit

The Remove Participants endpoint is the "Shield" of your community architecture. It allows you to maintain the integrity, security, and focus of your shared states. By treating membership pruning as a deliberate, strategic act rather than an afterthought, you build a conversational environment that is both efficient and professional. You ensure that every room your business owns is filled with exactly the right people, and that when their role is finished, they are transitioned out with precision and grace.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object
string

Your unique WhatsApp Instance ID

Example:
string

Your API Access Token

Example:
string

The unique ID of the group

Example:
array

List of JIDs to remove

Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/groups/1234567890@g.us/participants/remove";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7const body = {
8  "participants": [
9    {
10      "id": "1234567890@c.us"
11    }
12  ]
13};
14
15fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
16  method: "POST",
17  headers: { "Content-Type": "application/json" },
18  body: JSON.stringify(body)
19})
20  .then(async (response) => {
21    if (response.ok) {
22      const data = await response.json();
23      console.log("Success:", data);
24      return data;
25    }
26    
27    // Error Handling
28    
29
30    const errorText = await response.text();
31    console.error(`Error ${response.status}: ${errorText}`);
32  })
33  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 33, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Participants removed
application/json
boolean *

Example

{
"ok": true
}
Previous TopicAdd participants
Next TopicPromote participants to admin users

Command Palette

Search for a command to run...