QR Code Event

Triggered when a QR code is generated for WhatsApp authentication. Use this to display the QR code to users for scanning with their WhatsApp mobile app.

Event Type

qr-code

Payload Structure

{
  "event": "qr-code",
  "instanceId": "instance-uuid",
  "data": {
    "instanceId": "instance-uuid",
    "qr": "2@ABC123...",
    "expiresAt": 1702500060,
    "attempt": 1,
    "status": "pending",
    "timestamp": 1702500000
  }
}

Data Fields

Field	Type	Description
instanceId	string	Instance ID requesting authentication
qr	string	QR code data string
expiresAt	number	Unix timestamp when QR code expires
attempt	number | undefined	QR code generation attempt number
status	string	Current authentication status
timestamp	number	Unix timestamp when QR was generated

Displaying the QR Code

The qr field contains the raw QR code data. You can convert it to a scannable image using a QR code library.

JavaScript Example

import QRCode from 'qrcode';

app.post('/webhook', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'qr-code') {
    // Generate QR code image
    const qrImageUrl = await QRCode.toDataURL(data.qr);
    
    // Send to your frontend via WebSocket, SSE, etc.
    broadcastToClient(data.instanceId, {
      type: 'qr-code',
      imageUrl: qrImageUrl,
      expiresAt: data.expiresAt
    });
  }
  
  res.status(200).send('OK');
});

React Example

import { QRCodeSVG } from 'qrcode.react';

function QRCodeDisplay({ qrData, expiresAt }) {
  const [expired, setExpired] = useState(false);
  
  useEffect(() => {
    const timeout = setTimeout(() => {
      setExpired(true);
    }, (expiresAt * 1000) - Date.now());
    
    return () => clearTimeout(timeout);
  }, [expiresAt]);
  
  if (expired) {
    return <p>QR Code expired. Waiting for new code...</p>;
  }
  
  return (
    <div>
      <QRCodeSVG value={qrData} size={256} />
      <p>Scan with WhatsApp to connect</p>
    </div>
  );
}

QR Code Lifecycle

1. Instance created - QR code generation begins
2. qr-code event sent - First QR code available
3. User scans - Authentication in progress
4. QR expires - New qr-code event with incremented attempt
5. Authentication success - Instance connected

QR Code Expiration

QR codes expire after approximately 60 seconds. Monitor the expiresAt field and wait for a new qr-code event when it expires.

Multiple Attempts

If the user doesn't scan the QR code before it expires, a new one is generated automatically. The attempt field tracks how many QR codes have been generated:

{
  "attempt": 1,  // First QR code
  "attempt": 2,  // Second QR code (first expired)
  "attempt": 3   // Third QR code (second expired)
}

After several failed attempts, the instance may need to be restarted.