Default Behavior: Calling the endpoint without refresh: true will always prioritize the locally cached URL if it's less than 24 hours old. This is lightning fast and prevents unnecessary network round-trips. Forced Update: Only use refresh: true if your user explicitly triggers a "Refresh Profile" action in your

Get chat picture

Retrieve the profile picture URL of a chat (individual or group).

GET

https://api.wawp.net/v2/chats/picture?access_token=YOUR_ACCESS_TOKEN&chatId=201234567890%40c.us&instance_id=123456789&refresh=true

Authentication Required

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

Log In

Test /v2/chats/picture endpoint

Supports

GET

No query parameters required

This endpoint doesn't expect data in the URL.

Chat Profile Picture

Identify your contacts visually by fetching their latest WhatsApp profile picture.

Visual Identity: Mastering Chat Profile Picture Retrieval

In a professional messaging environment, visual context is key to reducing agent fatigue and improving response accuracy. The /v2/chats/picture endpoint allows you to programmatically fetch the latest high-resolution profile picture for any individual (@c.us) or group (@g.us). This ensures your internal CRM or dashboard feels integrated and up-to-date with the user's WhatsApp presence.

🏗️ The Lifecycle of a Profile Picture Fetch

When you call this endpoint, the Wawp engine handles a complex multi-step process:

Cache Verification: The engine checks its local 24-hour cache for an existing URL.
Privacy Check: It queries the WhatsApp network. If the user's privacy settings (e.g., "Profile Photo: My Contacts") restrict your instance from seeing the image, the network returns a null or restricted response.
High-Res Acquisition: If the image is available, Wawp attempts to fetch the highest resolution thumbnail provided by the network.
Base64/URL Delivery: The final result is returned as a direct URL (valid for a limited time) or can be cached locally by your system for persistence.

🚀 Performance and Cache Management

To maintain a responsive UI while respecting WhatsApp's rate limits, we implement a 24-Hour Smart Cache.

1. The "Bypass" Flag (`refresh`)

Default Behavior: Calling the endpoint without refresh: true will always prioritize the locally cached URL if it's less than 24 hours old. This is lightning fast and prevents unnecessary network round-trips.
Forced Update: Only use refresh: true if your user explicitly triggers a "Refresh Profile" action in your UI. Overusing this flag can lead to temporary "Visual Rate Limiting" where the network returns empty images to save bandwidth.

2. Strategic UI Placeholders (The "Initials" Fallback)

Because profile pictures can be restricted by privacy settings or deleted by the user, your UI must be resilient.

Pattern:
1. Try to fetch the URL via Wawp.
2. If the response is null, render a fallback avatar with the contact's initials (e.g., "JD" for John Doe) on a colored background.
3. Update the avatar only when a successful response is received.

🛡️ Best Practices for Identity Sync

Group vs. Individual: Group icons are usually easier to fetch because they use the "Public" group visibility. Individual pictures are more likely to be hidden by privacy settings.
Resolution Awareness: The returned URL usually points to a square thumbnail (e.g., 640x640). This is perfect for list views but may look pixelated in full-screen "About" sections. Always design your UI around a square aspect ratio.
CDN Validity: The URLs returned are often hosted on WhatsApp's CDNs and have a limited lifespan (TTL). Do not store these URLs permanently in your own database. Instead, store the binary image data or re-fetch the URL every time the user session starts.

🧩 Advanced Use Case: Contact Enricher

Build a routine that scans your "Top 50 Active Conversations" every morning.

Logic: Use /v2/chats/overview to identify active users, then call /v2/chats/picture for each. Store the images locally on your own server (S3/GCS) to ensure they are available even if the user changes their privacy settings later. This creates a permanent "Face-to-ID" mapping for your agents.

⚠️ Important Considerations

JID Precision: You must use the full JID. For groups, this is the ID ending in @g.us. If you use only the phone number without the suffix, the engine will fail to resolve the entity.
Privacy Walls: If a user has blocked your instance, you will never be able to see their profile picture. An empty response is often the first technical indicator of a block.
Engine State: Like other metadata endpoints, this works best when the session is in the WORKING state. If the session is STOPPED, tips: [ { type: 'info', title: 'Scope', content: 'Works for both Group chats and Private chats.' }, { type: 'warning', title: 'Privacy', content: 'May fail if the user's privacy settings hide their picture.' } ], recommendations: [ "Use 'contacts-profile-picture' for individual contacts.", "Handle 404/401 errors gracefully in your UI." ]

the engine cannot query the network for fresh images.

Summary of Capabilities:

High-resolution retrieval of contact and group avatars.
Integrated 24-hour caching for sub-second performance.
Support for forced refreshes to ensure visual data integrity.
Privacy-aware responses that respect user-level WhatsApp settings.

Request Parameters

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

URL Parameters

Passed in the URL query string

`string`		WhatsApp Instance ID Example:
`string`		API Access Token Example:
`string`		Target Chat ID (phone@c.us or group@g.us) Example:
`boolean`	—	Force refresh (bypass 24h cache) 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/chats/picture";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "YOUR_ACCESS_TOKEN",
6  "chatId": "201234567890@c.us",
7  "refresh": "true"
8}).toString();
9
10
11fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
12  method: "GET",
13  headers: { "Content-Type": "application/json" },
14  
15})
16  .then(async (response) => {
17    if (response.ok) {
18      const data = await response.json();
19      console.log("Success:", data);
20      return data;
21    }
22    
23    // Error Handling
24    if (response.status === 400) {
25      console.error("Error 400: Bad Request - Missing Required Parameter(s)");
26    }
27    if (response.status === 400) {
28      console.error("Error 400: Bad Request (XML Format)");
29    }
30    if (response.status === 400) {
31      console.error("Error 400: Bad Request (Plain Text)");
32    }
33    if (response.status === 401) {
34      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
35    }
36    if (response.status === 401) {
37      console.error("Error 401: Unauthorized (XML Format)");
38    }
39    if (response.status === 404) {
40      console.error("Error 404: Not Found - Session Does Not Exist");
41    }
42    if (response.status === 404) {
43      console.error("Error 404: Not Found (XML Format)");
44    }
45    if (response.status === 500) {
46      console.error("Error 500: Internal Server Error - Unexpected Failure");
47    }
48    if (response.status === 500) {
49      console.error("Error 500: Internal Server Error (HTML)");
50    }
51    if (response.status === 502) {
52      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
53    }
54    if (response.status === 502) {
55      console.error("Error 502: Bad Gateway (XML Format)");
56    }
57
58    const errorText = await response.text();
59    console.error(`Error ${response.status}: ${errorText}`);
60  })
61  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 61, 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.

Success - Request completed successfully

3 Variants

Type:

application/json

boolean *

string *

Example

{
"success": true,
"message": "Operation completed successfully"
}

Bad Request - Missing Required Parameter(s)