Instance Login

Get QR Image

Returns a base64-encoded PNG image of the WhatsApp QR code for easy rendering in web and mobile applications.

POST
https://api.wawp.net/v2/auth/qr-image?access_token=YOUR_ACCESS_TOKEN&instance_id=Your_Instance_ID

Authentication Required

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

Log In
Test /v2/auth/qr-image endpoint
POSTGET

No query parameters required

This endpoint doesn't expect data in the URL.

Best practices

  • Embed directly in your frontend without saving to disk for better security.

  • Refresh the image every 30 seconds to avoid showing expired codes.

  • Do not cache this response; always fetch a fresh image.

The Visual Gateway: A Masterclass in QR Image Authentication

The /v2/auth/qr-image endpoint is the gold standard for web-based WhatsApp integrations. It abstracts away the complexity of raw binary data and Base64 decoding, providing a ready-to-use Data URI that can be injected directly into any modern browser environment. This endpoint is specifically tuned for speed and ease of use in React, Vue, and vanilla JS dashboards.

🏗️ Anatomy of the Data URI Response

When you call this endpoint, you receive a JSON response containing a single qr field. This field contains a string prefixed with data:image/png;base64,....

  • The Core Value: This is a high-contrast, optimized PNG image of the WhatsApp pairing code.
  • Frontend Implementation: 
    // Example: Updating an image element in Vanilla JS
fetch('/v2/auth/qr-image', { method: 'POST', body: JSON.stringify({ instance_id, access_token }) })
  .then(res => res.json())
  .then(data => {
    document.getElementById('qr-container').src = data.qr;
  });

🛡️ Strategic Best Practices

1. Intelligent UI Polling

Because QR codes refresh frequently (every 20-40 seconds), your UI needs a "Heartbeat."

  • The Strategy: Set an interval to refresh the image every 5-10 seconds. This ensures that when the user finally holds up their phone to scan, the code they see is guaranteed to be within its valid window.
  • Visual UX: Implement a subtle "Pulse" animation or a loading overlay when the image is refreshing to inform the user that the system is keeping the link alive.

2. Mastering the 422 Auto-Recovery State

One of Wawp’s unique features is the Background Engine Healer. If you call this endpoint and the engine is currently de-synced from WhatsApp, it will return a 422 Session Status Not Expected error.

  • The Lifecycle: This response signals that our cloud orchestrator has detected a stall and is currently performing a Stop -> Start sequence for you automatically.
  • Developer Action: Do not show an "Operation Failed" error. Instead, show a message like "Recovering the engine bridge... please wait 15 seconds." After the delay, retry the request—you will likely be greeted with a fresh, working QR code.

3. Cache Management

To prevent accidental exposure of sensitive QR data, this endpoint is served with strict Cache-Control: no-store headers.

  • Warning: Never attempt to bypass these headers. Storing a QR image in a CDN or browser cache is a security risk and will lead to "Failed to scan" errors for the user, as the cached code will be stale.

💡 Developer Use Cases

A. Mobile-Responsive Dashboards

The PNG returned by this endpoint is dynamically generated to be high-contrast and clear even on low-budget smartphone displays. This makes it perfect for "Scan on iPad" or "Scan on Chromebook" scenarios where screen glare can sometimes interfere with lower-quality QR renderers.

B. Onboarding Progress Bars

By monitoring the response of this endpoint in parallel with /v2/session/info, you can build a multi-step onboarding wizard:

  1. Step 1: "Warming up engine" (Poll until Status is SCAN_QR_CODE).
  2. Step 2: "Ready to Scan" (Fetch and display the QR image).
  3. Step 3: "Success!" (Transition to WORKING).

⚠️ Common Pitfalls

  • GET Request Leakage: Avoid using GET requests for this endpoint in production dashboards. Browsers often log GET parameters (like your access_token) in the command history or developer console. Use POST to keep your credentials in the request body.
  • Ignoring the Mimetype: Always ensure your image tag or CSS background-image property correctly handles the data:image/png;base64 prefix. Omitting this part of the string will result in a "Broken Image" icon.

Summary of Capabilities:

  • Instantly retrieve a scan-ready PNG image of the WhatsApp QR code.
  • Leverage the "One-Click" rendering power of Data URIs.
  • Trigger automatic environment healing during state de-syncs.
  • Maintain high security with non-persistent, non-cached visual data.

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

The 12-character ID of the instance

Example:
string

Your API Access Token

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/auth/qr-image";
3const params = new URLSearchParams({
4  "instance_id": "Your_Instance_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
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 - Missing Required Parameter(s)");
24    }
25    if (response.status === 400) {
26      console.error("Error 400: Bad Request (XML Format)");
27    }
28    if (response.status === 400) {
29      console.error("Error 400: Bad Request (Plain Text)");
30    }
31    if (response.status === 401) {
32      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
33    }
34    if (response.status === 401) {
35      console.error("Error 401: Unauthorized (XML Format)");
36    }
37    if (response.status === 404) {
38      console.error("Error 404: Not Found - Session Does Not Exist");
39    }
40    if (response.status === 404) {
41      console.error("Error 404: Not Found (XML Format)");
42    }
43    if (response.status === 500) {
44      console.error("Error 500: Internal Server Error - Unexpected Failure");
45    }
46    if (response.status === 500) {
47      console.error("Error 500: Internal Server Error (HTML)");
48    }
49    if (response.status === 502) {
50      console.error("Error 502: Bad Gateway - Connection Failed to Upstream");
51    }
52    if (response.status === 502) {
53      console.error("Error 502: Bad Gateway (XML Format)");
54    }
55    if (response.status === 422) {
56      console.error("Error 422: Unprocessable Entity - Session Status Mismatch");
57    }
58
59    const errorText = await response.text();
60    console.error(`Error ${response.status}: ${errorText}`);
61  })
62  .catch((error) => console.error("Network Error:", error));
Interactive Samples
Ln 62, 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 - QR Image URL
Type:
application/json
string *

Example

{
"qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}
Bad Request - Missing Required Parameter(s)
Unauthorized - Invalid or Missing Access Token
Not Found - Session Does Not Exist
Unprocessable Entity - Session Status Mismatch
Internal Server Error - Unexpected Failure
Bad Gateway - Connection Failed to Upstream
Previous TopicGET QR raw
Next TopicSend OTP

Command Palette

Search for a command to run...