Groups

Promote participants to admin users

Promote one or more participants to group admins.

POST
https://api.wawp.net/v2/groups/{id}/admin/promote?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}/admin/promote endpoint
POST
POST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Limit the number of admins to simplify governance.

  • Use a specific role tag in your CRM for promoted users.

  • Audit admin lists periodically.

Delegating Authority: The Strategic Elevation of Community Leaders

In the complex orchestration of enterprise WhatsApp groups, the Promote Participants endpoint is the primary tool for Distributed Governance. It allows you to programmatically elevate regular members to the status of Group Administrators, granting them the local authority required to manage the community natively from their own devices. This endpoint is the key to building "Hybrid Moderation" models where your Wawp instance provides the high-level automation, while trusted human stakeholders handle the day-to-day interpersonal management of the chat.

For architects, "Promotion" is the act of Delegating State Control. This guide explores the strategic implications of admin elevation and how to manage the privilege matrix effectively at scale.

🏗️ Architectural Philosophy: The Elevation of State Permissions

From a technical perspective, promoting a participant is a Permission Mask Update. You are transitioning a JID from a "ReadOnly/Interact" state to a "Write-Metadata/Manage-State" state.

The Admin Privilege Matrix

When a user is promoted via this endpoint, they gain a suite of local capabilities in their WhatsApp app that are previously restricted. A promoted admin can:

  • Modify Global Metadata: Change the group subject, description, and profile picture (depending on group settings).
  • Manage the Population: Add new members directly or remove existing ones.
  • Influence Governance: Promote other members to admin (though they cannot demote the original Creator).
  • Enforce Silence: Toggle the "Announcement Mode" to lock or unlock the group for participant messages.

The Power of the Super-Admin (API Creator)

It is vital to remember that while the API can create many admins, the Wawp instance that initialized the group remains the Super-Admin/Creator. This hierarchy ensures that even if a promoted admin attempts to be disruptive, your system maintains the "Master Override" capability. Promotion is a delegation of operational power, not absolute ownership.

🚀 Strategic Use Case: Hybrid Moderation and Human-in-the-Loop

The most effective community strategies combine the speed of AI with the nuance of human judgment.

1. Enabling Local Autonomy for Field Agents

In a large-scale real estate or project management deployment, your system might create hundreds of groups. By automatically Promoting the assigned field agent to admin status, you empower them to manage the group "on the fly" while they are on-site with a client. They can add a subcontractor or change the group subject to reflect a status update without needing to log into a specialized CRM dashboard. The API handles the creation and initial setup, while the promotion grants the human agent the "Boots-on-the-Ground" flexibility they need.

2. The "Community Champion" Incentive

For customer-facing communities (e.g., a fan group or a product feedback cohort), promotion can be used as a reward for high engagement. Your system can track message volume and sentiment; once a user crosses a specific "Trust Threshold," the system automatically promotes them to admin, turning them into a volunteer moderator. This "Automated Meritocracy" helps scale community management without increasing your business's headcount.

3. Escalation-Based Authority Injection

In a standard support group, agents might function as regular members to keep the power centralized. However, if your system detects a "Critical Escalation" (via keyword analysis or a sentiment trigger), it can instantly Promote a Senior Manager to admin status. This provides the manager with the immediate "Executive Tools" needed to lock down the group or remove disruptive parties during a crisis.

🔐 Security & Trust: Managing the Risk of Decentralized Authority

Granting admin rights is a high-trust event that carries inherent risks. A rogue admin can create significant disruption before your automation can react.

The "Governance Audit" Cycle

To mitigate the risk of "Admin Bloat," your system should implement a periodic audit. Using the Get Group Info endpoint, your system should scan the membership list and compare the current admins against your internal "Authorized Admin Whitelist." Any user found with admin rights who isn't on the whitelist can be automatically Demoted to restore the governance baseline.

Participant Visibility and Compliance

Admin status grants a user more visibility into group activity. In regulated industries, you must ensure that only verified employees are ever promoted. Your system should cross-reference the JID of any promotion target with your internal HR or Active Directory records to prevent accidental elevation of a customer or a third-party contractor to a position of authority over the group state.

🛡️ Operational Hygiene and Best Practices

  • Idempotency of Elevation: Promoting a user who is already an admin is a safe, no-op operation. This allows your system to "Re-Assert" authority during a recovery sequence without fearing errors or duplicate state changes.
  • Throttling Bulk Promotions: While the endpoint allows for multiple JIDs, we recommend promoting individuals one by one or in small batches. Large numbers of simultaneous admin changes can sometimes be flagged by Meta's security heuristics as "Account Hijacking" patterns.
  • System Notifications & Professionalism: Every promotion triggers a system notification in the chat ("Business Name made [User] an admin"). This is a public signal of trust. Your system should often follow this up with a 1:1 message to the newly promoted admin, providing them with a "Moderator Guide" or a list of responsibilities.

⚙️ Engineering Best Practices: The Validation Loop

  1. Verify Admin Status of the Instance: Your Wawp instance must be a Group Admin to promote others. Always perform a pre-flight check of your own permissions before attempting to change the permissions of others.
  2. Verify Membership: You cannot promote someone who is not currently a member of the group. Attempting to do so will result in an API error. A robust workflow includes an Add -> Verify -> Promote sequence for new stakeholders.
  3. Webhook Integration: Ensure your system listens for the group.participants.update webhook. When the WhatsApp network confirms the promotion, your system should update its internal "Authority Map" so that your UI correctly identifies which users are moderators.

🎯 Conclusion: Mastering the Art of Delegated Success

The Promote Participants endpoint is the tool that transforms a monolithic bot into a dynamic community ecosystem. By strategically delegating authority to trusted humans and secondary automated instances, you build a conversational architecture that is resilient, scalable, and responsive to the needs of its members. You empower your team to lead, while your system maintains the foundational governance that ensures the community's long-term health and alignment with your business goals.

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 promote

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/admin/promote";
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 promoted
application/json
boolean *

Example

{
"ok": true
}
Previous TopicRemove participants
Next TopicDemotes participants to regular users

Command Palette

Search for a command to run...