Refresh groups from the server

Force a refresh of the groups list from WhatsApp servers.

POST
https://api.wawp.net/v2/groups/refresh?access_token=123456789&instance_id=123456789

Authentication Required

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

Log In
Test /v2/groups/refresh endpoint
POST
POST

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Call this only if you suspect your local state is desynchronized.

  • Use this after a network outage to catch up on missed changes.

Synchronization and the Reclamation of Truth: The Strategic Force of Refreshing

In the complex, distributed environment of Meta's messaging infrastructure, state eventually drifts. The Refresh Groups endpoint is your primary tool for Manual State Reconciliation and Architectural Realignment. While the Wawp API utilizes an advanced, event-driven architecture to keep your group lists synchronized in real-time, there are edge cases—such as account recovery, network partitions, or rapid multi-device modifications—where the local cache might require a definitive "Hard Reset" to match the network's ground truth. By calling this endpoint, you instruct your instance to bypass its local storage and perform a full, authoritative query of Meta's global group directory.

For enterprise architects, the "Refresh" is the Ultimate Corrective Power. This guide explores the strategic imperatives of synchronization and the reclamation of technical truth.


🏗️ Architectural Philosophy: The Manual Trigger of Global Reconciliation

From a technical perspective, the Refresh Groups endpoint is a Cache Invalidation and Re-Index Command.

Key Architectural Objectives:

  • Reclaiming the Ground Truth: When your instance is first Linked or after a long period of inactivity, the local knowledge of group memberships may be incomplete. The Refresh call forces the instance to crawl its own internal protocol storage and reconcile it with the server's state, ensuring that your List Groups and Count Groups calls return 100% accurate data.
  • Overcoming Webhook Gaps: In rare scenarios where a webhook notification was missed due to a server downtime or a networking error, the state of a group's existence (e.g., whether your instance was Removed) might become stale. Refreshing is the "Self-Healing" mechanism that fixes these discrepancies without requiring complex manual investigation.
  • Structural Re-Indexing: This endpoint is particularly useful after large-scale administrative changes (like a corporate merge where hundreds of groups are created by a different admin). It ensures that your API instance "Discovers" its new memberships as quickly as possible.

🚀 Strategic Use Case: Recovery Sequences and Multi-Account Auditing

The Refresh Groups endpoint should be a core component of your system's "Disaster Recovery" and "Health Audit" routines.

1. The "Instance Awakening" Protocol

When a new WhatsApp instance is initialized or an existing one is re-authenticated after a logout, its initial "Group Awareness" may be zero. Your system should automatically call the Refresh Groups endpoint as the final step of the Onboarding Flow. This ensures that when your human agents first log into your CRM dashboard, they see their entire community portfolio immediately, rather than waiting for the background sync to catch up incrementally.

2. The "Pre-Campaign" Integrity Check

Before launching a massive broadcast campaign that targets participants across 500 different groups, you must ensure that your instance is still a member of every target group. Calling the Refresh Groups endpoint 5 minutes before the campaign starts acts as a "Read-Ready" verification. It ensures that your message delivery engine isn't attempting to send packets to groups you've been kicked out of, lowering your error rate and protecting your account's sender reputation.

3. Automated State Sanitization (The Weekly Warden)

We recommend implementing a "Weekly Warden" cron job that calls the Refresh Groups endpoint during off-peak hours. This routine maintenance ensures that any minor state drifts that have accumulated over 168 hours of operation are corrected. It keeps your database and Meta's infrastructure in "Perfect Harmony," providing a clean foundation for your weekly reporting and analytics.


🔐 Administrative Mandate: Authority and the Integrity of the Group List

Maintaining a synchronized state is a core requirement of professional governance.

Visibility is the Foundation of Control

If your API doesn't "Know" it's in a group, it cannot moderate that group, audit its participants, or respond to its messages. The Refresh Groups endpoint is therefore a security tool. By ensuring your list is fresh, you ensure that no group falls through the cracks of your automated oversight logic. It eliminates the "Blind Spots" in your conversational ecosystem.

Identifying "Unauthorized Removals"

By calling the Refresh endpoint and then comparing the result with your internal CRM's "Expected Groups" list, you can programmatically detect if your business has been removed from a high-value community. This allows your system to trigger an "Escalation Workflow"—notifying an account manager to re-contact the client and request a Re-Join—before the relationship is damaged by a silent absence.


🛡️ Operational Best Practices: Throttling and Resource Stewardship

  • Avoid "Spammy" Refreshing: Refreshing is a resource-intensive operation because it requires the instance to probe multiple server-side endpoints. Do not call this endpoint more than once every 15-30 minutes under normal circumstances. Overuse can lead to temporary rate-limiting by Meta's infrastructure.
  • The "Silent Progress" Indicator: Since a full refresh can take several seconds for instances with hundreds of groups, ensure your UI provides a "Syncing..." status. This manages human agent expectations and prevents them from clicking the refresh button multiple times in frustration.
  • Coordinate with Webhooks: Remember that a successful refresh will often trigger a burst of group.update or group.join webhooks as the state is reconciled. Ensure your backend infrastructure is scaled to handle this temporary spike in incoming data.

⚙️ Engineering Best Practices: The Validation Loop

  1. POST-Initialization Wait: If you have just created 50 groups in a single batch, wait at least 30-60 seconds before calling a global Refresh. This gives the global network time to finalize the state changes across all regional servers.
  2. Idempotent State Check: After a Refresh call returns success, immediately follow up with a Get Groups Count or List Groups call to fetch the newly reconciled data and update your local database's source of truth.
  3. Error-Resilient Retries: If a Refresh call fails due to a network timeout, use an exponential backoff strategy for retries. Forced synchronization is critical, but it shouldn't overwhelm your instance during periods of unstable connectivity.

🎯 Conclusion: Mastering the Art of the Synchronized Community

The Refresh Groups endpoint is the "Reset Button" for your community architecture. It is your most powerful tool for ensuring that your automated systems are operating on the most current, authoritative data provided by the WhatsApp network. By treating synchronization as a deliberate, strategic operation, you build a conversational environment that is resilient to drift, transparent to its stakeholders, and always perfectly aligned with its operational goals. You move beyond "Passive Reception" and into the world of Proactive State Management, where the integrity of your community list is a Choice, not a Chance.

Request Parameters

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

Query Parameters & Request Body

Supported in URL Query String or JSON Body
string

Your unique WhatsApp Instance ID

Example:
string

Your API Access Token

Example:

Build with AI using Wawp MCP

MCP READY

Connect Wawp API directly to Cursor, Windsurf, or Claude Desktop. Let AI write, test, and execute your WhatsApp integration code automatically!

How to Connect

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/refresh";
3const params = new URLSearchParams({
4 "instance_id": "123456789",
5 "access_token": "123456789"
6}).toString();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10 method: "POST",
11 headers: { "Content-Type": "application/json" },
12
13})
14 .then(async (response) => {
15 if (response.ok) {
16 const data = await response.json();
17 console.log("Success:", data);
18 return data;
19 }
20
21 // Error Handling
22 if (response.status === 400) {
23 console.error("Error 400: Bad Request - Invalid Parameter Format");
24 }
25 if (response.status === 401) {
26 console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
27 }
28 if (response.status === 500) {
29 console.error("Error 500: Internal Server Error - Unexpected Failure");
30 }
31
32 const errorText = await response.text();
33 console.error(`Error ${response.status}: ${errorText}`);
34 })
35 .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 35, 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.

Groups refreshed
application/json
boolean *

Example

{
"ok": true
}
Bad Request - Invalid Parameter Format
Unauthorized - Invalid or Missing Access Token
Internal Server Error - Unexpected Failure
Previous TopicGet the number of groups
Next TopicGet the group

Command Palette

Search for a command to run...