> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request New QR Code

> Generate a new QR code for instance authentication after an expired or failed scan.

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:

```html theme={null}
<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`

<Warning>
  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.
</Warning>

<Tip>
  Consider implementing a timer in your UI to show when users can request a new QR code after hitting the rate limit.
</Tip>

## 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


## OpenAPI

````yaml v2/api-reference/enterprise/enterprise-collection.json POST /{instance}/request-new-qr-code
openapi: 3.1.0
info:
  version: v1.0
  title: Hypersender Enterprise API Docs
  description: >

    The Hypersender Enterprise API provides powerful management capabilities for
    WhatsApp instances.


    In this Docs you'll learn how to use and integrate Hypersender Enterprise
    API into your existing system/service or application using simple API
    endpoints.


    **What you can Do?**


    - Check instance health status

    - List all instances with filtering

    - Create new WhatsApp instances

    - Request new QR codes for authentication

    - Restart instances


    <hr />


    ## Servers (Endpoints)


    - Production (activated):
    [https://app.hypersender.com/api/whatsapp/v2](https://app.hypersender.com/api/whatsapp/v2)
servers:
  - url: https://app.hypersender.com/api/whatsapp/v2
    description: Production
security:
  - Authorization: []
paths:
  /{instance}/request-new-qr-code:
    post:
      tags:
        - Instance Management
      summary: Request New QR Code
      description: >-
        Forces the instance to generate a new QR code, typically after an
        expired or failed scan. This endpoint is limited to 1 request per
        minute.
      parameters:
        - name: Accept
          in: header
          description: application/json
          schema:
            type: string
            example: application/json
        - name: instance
          in: path
          description: Instance UUID copied from hypersender dashboard
          required: true
          schema:
            type: string
            example: '{{ instance_id }}'
      responses:
        '200':
          description: New QR code generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceWithQRResponse'
              example:
                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'
        '404':
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests. Please try again later.
      security:
        - Authorization: []
components:
  schemas:
    InstanceWithQRResponse:
      allOf:
        - $ref: '#/components/schemas/InstanceResponse'
        - type: object
          properties:
            qr_code:
              type: string
              description: >-
                Base64-encoded PNG QR code (without data:image/png;base64,
                prefix). You must prepend it manually when displaying: <img
                src="data:image/png;base64,{{qr_code}}" />
              example: iVBORw0KGgoAAAANSUhEUgAAA...
    NotFoundError:
      type: object
      title: NotFoundError
      example:
        message: Resource not found.
      properties:
        message:
          type: string
    InstanceResponse:
      type: object
      properties:
        id:
          type: string
          description: Instance UUID
          example: fa3d01c4-1234-4c0d-a12f-df319b612f8c
        name:
          type: string
          description: Instance name
          example: MyInstanceName
        phone:
          type: string
          description: Phone number in E.164 format
          example: '+201234567890'
        service_type:
          type: string
          description: Service type
          example: whatsapp
        status:
          type: string
          enum:
            - STOPPED
            - STARTING
            - WORKING
            - SCAN_QR_CODE
            - FAILED
            - PENDING
          description: Instance status
          example: WORKING
        access_token:
          type:
            - string
            - 'null'
          description: Access token for the instance
          example: 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1
        created_at:
          type: string
          description: Creation timestamp
          example: '2025-05-26T10:12:45'
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication. Example: `Bearer
        234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1`

````