استخراج صورة رمز QR

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;
    });
  

  Copy

🛡️ 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.