GET QR raw

Retrieves the raw QR payload as binary/base64 plus a mimetype.

POST

https://api.wawp.net/v2/auth/qr?access_token=YOUR_ACCESS_TOKEN&format=raw&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 endpoint

Supports

POSTGET

No query parameters required

This endpoint doesn't expect data in the URL.

Freshness

This endpoint returns a non-cached response header to ensure you always get the latest QR code.

Expiry

The returned QR string has a short lifespan (20-60s). Use the 'expiry' timestamp to refresh it.

Best practices

Use this endpoint for custom CLI dashboards or mobile app integrations.
Decode the Base64 'data' field before passing it to a QR generation library.
Implement a polling mechanism to fetch a new code upon expiry.

Deciphering the Protocol: The Raw QR Payload Guide

The /v2/auth/qr endpoint is the specialized "Engine Access" tool for developers who require surgical control over the authentication process. Unlike the image-based endpoint, which is optimized for quick rendering, this route provides the raw, Base64-encoded protocol string. This is essential for building custom QR generators, CLI-based tools, or native mobile implementations where binary data is preferred over a static image.

🏗️ Technical Breakdown: The JSON Envelope

The response from this endpoint is a JSON object containing two primary components:

mimetype: Typically application/json, indicating that the payload is a structured data object.
data: A Base64-encoded string. Once decoded, this string yields a JSON object containing the Protocol Signature required by the WhatsApp WebSocket.

The Decoded Payload Structure

When you decode the data field, you will find:

value: The actual alphanumeric string that needs to be encoded into a QR pattern.
expiry: A Unix timestamp representing the exact millisecond when this specific QR code will be invalidated by the WhatsApp servers.

🛡️ Strategic Best Practices

1. Implementing a CLI-Based ASCII Renderer

If you are building a headless tool (like a VPS manager or a terminal-based bot), fetching the raw QR string allows you to render the code directly in the terminal using ASCII characters.

Developer Action: Use a library like qrcode-terminal in Node.js or qrcode in Python. Pass the value from the decoded response to the library to display the scanable pattern directly to your server administrators.

2. Synchronization and Rate Limiting

Fetching the raw QR is a relatively resource-intensive task for the underlying engine as it involves a real-time probe of the browser state.

The Polling Window: We recommend a polling interval of 5-7 seconds. Polling faster than this will not yield a "fresher" code (as WhatsApp only rotates codes every 20-30 seconds) and may lead to 429 Rate Limit responses from our infrastructure.

3. Handling the Recovery Window (422 Status)

If the engine is busy resetting its internal WhatsApp bridge, you will receive a 422 Session Status Not Expected error.

The Fix: This is not a failure; it’s a "Please Wait" signal. Your application should implement an exponential backoff. Wait 10 seconds, then 20 seconds, before attempting to fetch the QR again. This gives the engine time to finalize its background handshake.

💡 Industry-Standard Use Cases

A. Deep-Link Mobile Integration

If you are building a native iOS or Android app, you can fetch the raw QR string and use the mobile OS's native QR generation libraries (like CoreImage on iOS). This results in a much sharper, high-contrast QR code that is easier for the user's secondary device to scan compared to a compressed PNG image.

B. Security-Hardened Dashboards

For high-security environments where you do not want to load external images from our servers, you can fetch the raw string on your backend, verify its integrity, and then generate the QR pattern locally using your own internal corporate styling.

⚠️ Common Pitfalls

Binary vs. String: The data field is Base64 encoded. If you try to pass the raw Base64 string directly into a QR generator without decoding it first, the scan will fail because the data will be interpreted as a literal Base64 string rather than the underlying WhatsApp protocol ID.
Expiry Ignorance: Always check the expiry field. If your frontend displays a QR code that has already passed its expiry timestamp, the user will scan it only to see an "Expired" error on their phone, leading to significant UX frustration.

Summary of Responsibilities:

Retrieve the raw cryptographic string required for a WhatsApp handshake.
Provide a Base64-wrapped JSON envelope for protocol compatibility.
Enable custom rendering in non-browser environments (CLI, Mobile).
Facilitate advanced monitoring of QR rotation cycles and expiration.

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:
`string`	—	Output format (default: raw) 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";
3const params = new URLSearchParams({
4  "instance_id": "Your_Instance_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "format": "raw"
9};
10
11fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
12  method: "POST",
13  headers: { "Content-Type": "application/json" },
14  body: JSON.stringify(body)
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    if (response.status === 422) {
58      console.error("Error 422: Unprocessable Entity - Session Status Mismatch");
59    }
60
61    const errorText = await response.text();
62    console.error(`Error ${response.status}: ${errorText}`);
63  })
64  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 64, 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 Raw Data

3 Variants

Type:

application/json

string *

Example

{
"mimetype": "application/json; charset=utf-8",
"data": "eyJ2YWx1ZSI6IjJAR0JoWWtpTkV1U0tpeXpIeVVOYy9RQi9lTnhpSkJWSE96bGhOQ1daRERvRUZyOEhDWEhxTENKdEVpZHh6WWoxWkpqRzZ4K2NOaFVlVGlZeUJHWExJQzU1Z2ppKzRHQ2VyakRvPSIsImV4cGlyeSI6MTIzNDU2Nzg5MH0="
}

Bad Request - Missing Required Parameter(s)

3 Variants

Unauthorized - Invalid or Missing Access Token

2 Variants

Command Palette

Search for a command to run...