Skip to main content
POST
/
{instance}
/
request-new-qr-code
Request New QR Code
curl --request POST \
  --url https://app.hypersender.com/api/whatsapp/v1/{instance}/request-new-qr-code \
  --header 'Authorization: Bearer <token>'
{
  "id": "c9a1dd76-5678-4f9d-9012-a5b78de100c3",
  "name": "MyInstanceName",
  "phone": "+201234567890",
  "service_type": "whatsapp",
  "status": "SCAN_QR_CODE",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAA...",
  "access_token": "234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1",
  "created_at": "2025-05-26T10:12:45"
}
Force the instance to generate a new QR code when the previous one has expired or the scan failed. This is useful when users take too long to scan the QR code or encounter connection issues.

​
Rate Limit

This endpoint is limited to 1 request per minute to prevent abuse and protect against rapid QR code generation attempts.

​
When to Use

Use this endpoint when:
  • The QR code has expired (typically after 60 seconds)
  • The initial QR code scan failed
  • The user closed the scanning interface without completing authentication
  • You need to refresh the authentication flow

​
Response

The response includes:
  • Updated instance details
  • qr_code - New base64-encoded PNG QR code
  • Current instance status (should be SCAN_QR_CODE)
  • access_token - Your instance access token

​
QR Code Display

The QR code is returned as a base64-encoded PNG without the data URI prefix. To display it in HTML: 
<img src="data:image/png;base64,{qr_code}" alt="WhatsApp QR Code" />

​
Authentication Flow

  1. Request a new QR code
  2. Display it to the user
  3. User scans with WhatsApp mobile app (Settings > Linked Devices)
  4. Monitor instance status until it changes to WORKING
Due to the rate limit of 1 request per minute, avoid calling this endpoint repeatedly. Implement proper error handling and inform users about the cooldown period.
Consider implementing a timer in your UI to show when users can request a new QR code after hitting the rate limit.

​
Error Responses

  • 404: Instance not found - Check if the instance UUID is correct
  • 429: Rate limit exceeded - Wait at least 60 seconds before requesting again

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Example: Bearer 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1

Headers

​
Accept
string

application/json

Example:

"application/json"

Path Parameters

​
instance
string
required

Instance UUID copied from hypersender dashboard

Example:

"{{ instance_id }}"

Response

New QR code generated successfully

​
id
string

Instance UUID

Example:

"fa3d01c4-1234-4c0d-a12f-df319b612f8c"

​
name
string

Instance name

Example:

"MyInstanceName"

​
phone
string

Phone number in E.164 format

Example:

"+201234567890"

​
service_type
string

Service type

Example:

"whatsapp"

​
status
enum<string>

Instance status

Available options:
STOPPED,
STARTING,
WORKING,
SCAN_QR_CODE,
FAILED,
PENDING
Example:

"WORKING"

​
access_token
string | null

Access token for the instance

Example:

"234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1"

​
created_at
string

Creation timestamp

Example:

"2025-05-26T10:12:45"

​
qr_code
string

Base64-encoded PNG QR code (without data:image/png;base64, prefix). You must prepend it manually when displaying:

Example:

"iVBORw0KGgoAAAANSUhEUgAAA..."