WhatsApp QR Code Collection API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses QR…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: QR Code Collection
  description: APIs for listing and creating WhatsApp Business message QR codes
paths:
  /{Version}/{Phone-Number-ID}/message_qrdls:
    get:
      summary: List All Message QR Codes
      description: 'Retrieve all message QR codes for a phone number, sorted by creation time (newest first).

        Supports field selection, filtering by code, cursor-based pagination, and QR image generation.'
      operationId: listAllQrCodes
      tags:
      - QR Code Collection
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: Phone-Number-ID
        in: path
        required: true
        description: 'The WhatsApp Business Account phone number ID for which to list QR codes.

          This ID is provided when you add a phone number to your WhatsApp Business Account.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: fields
        in: query
        required: false
        description: 'Comma-separated list of fields to include in the response. Available fields:

          - code: QR code identifier (always included)

          - prefilled_message: Pre-filled message text (always included)

          - deep_link_url: WhatsApp deep link URL (always included)

          - creation_time: Unix timestamp when QR code was created (first-party apps only)

          - qr_image_url.format(FORMAT): QR code image URL where FORMAT is SVG or PNG


          Example: "code,prefilled_message,qr_image_url.format(SVG)"

          '
        schema:
          type: string
        example: code,prefilled_message,deep_link_url,qr_image_url.format(SVG)
      - name: code
        in: query
        required: false
        description: 'Filter results to a specific QR code by its unique identifier.

          When provided, only the matching QR code will be returned (if it exists).

          '
        schema:
          type: string
          pattern: ^[A-Z2-7]{14}$
          minLength: 14
          maxLength: 14
        example: ANED2T5QRU7HG1
      - name: limit
        in: query
        required: false
        description: 'Maximum number of QR codes to return in a single response.

          Default and maximum limit is typically 25.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 25
          default: 25
        example: 10
      - name: after
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the next page of results.

          Obtain this value from the paging.cursors.after field in previous responses.

          '
        schema:
          type: string
        example: MTYwNDYxNzIwMQ==
      - name: before
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the previous page of results.

          Obtain this value from the paging.cursors.before field in previous responses.

          '
        schema:
          type: string
        example: MTYwNDYxNzIwMA==
      responses:
        '200':
          description: Successfully retrieved the list of message QR codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QrCodeList'
              examples:
                default_fields:
                  summary: Default fields response
                  description: Response with default fields (code, prefilled_message, deep_link_url)
                  value:
                    data:
                    - code: 5QBPAD2DC6L5A1
                      prefilled_message: Show me Cyber Tuesday deals!
                      deep_link_url: https://wa.me/message/5QBPAD2DC6L5A1
                    - code: ANED2T5QRU7HG1
                      prefilled_message: Show me Cyber Monday deals!
                      deep_link_url: https://wa.me/message/ANED2T5QRU7HG1
                    - code: WOMVT6TJ2BP7A1
                      prefilled_message: Tell me more about your production workshop
                      deep_link_url: https://wa.me/message/WOMVT6TJ2BP7A1
                with_qr_image:
                  summary: Response with QR code image
                  description: Response including QR code image URL in SVG format
                  value:
                    data:
                    - code: FO7JXE4BG3RFG1
                      prefilled_message: Tell me more about your event planning packages
                      deep_link_url: https://wa.me/message/FO7JXE4BG3RFG1
                      qr_image_url: https://scontent-iad3-1.xx.fbcdn.net/m1/v/t6/An-H7T8OyTqO07lcRGHlKteuPMKDnx07nua3dGb4i560bVxDscweOV4KoKD_4wCDFoHR_C5LyVjxQISKPxwora1bbFhUEo2nA19ZPLBUVoQSmV12l1x-nuu312jKty-5rmojmde_a0g?ccb=10-5&oh=00_AfASq_vjojFza_9A-HDeRgHM3wZ8yjNprpYBjNKOn8RkSg&oe=64550A9E&_nc_sid=f36290
                single_qr_code:
                  summary: Filtered by specific QR code
                  description: Response when filtering by a specific QR code ID
                  value:
                    data:
                    - code: ANED2T5QRU7HG1
                      prefilled_message: Show me Cyber Monday deals!
                      deep_link_url: https://wa.me/message/ANED2T5QRU7HG1
                empty_response:
                  summary: No QR codes found
                  description: Response when no QR codes exist or match the filter criteria
                  value:
                    data: []
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid fields parameter. Check field names and format specifications
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to list QR codes for this phone number
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Phone number not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Too many API calls. Please try again later
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
    post:
      summary: Create or Update Message QR Code
      description: 'Create a new QR code (without code parameter) or update existing QR code (with code parameter).

        Supports optional QR image generation in PNG or SVG format.'
      operationId: createOrUpdateQrCode
      tags:
      - QR Code Collection
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: Phone-Number-ID
        in: path
        required: true
        description: 'The WhatsApp Business Account phone number ID for which to create or update the QR code.

          This ID is provided when you add a phone number to your WhatsApp Business Account.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CreateQrCodeRequest'
              - $ref: '#/components/schemas/UpdateQrCodeRequest'
            examples:
              create_qr_code:
                summary: Create new QR code with SVG image
                description: Creates a new QR code and generates an SVG image
                value:
                  prefilled_message: Hi! I'm interested in your products. Can you help me?
                  generate_qr_image: SVG
              create_qr_code_png:
                summary: Create new QR code with PNG image
                description: Creates a new QR code and generates a PNG image
                value:
                  prefilled_message: Hello! I'd like to get more information about your services.
                  generate_qr_image: PNG
              create_qr_code_no_image:
                summary: Create new QR code without image
                description: Creates a new QR code without generating an image file
                value:
                  prefilled_message: I'm interested in learning more about your business!
              update_existing_qr_code:
                summary: Update existing QR code message
                description: Updates the pre-filled message for an existing QR code
                value:
                  code: ANED2T5QRU7HG1
                  prefilled_message: Hello! I'd like to know more about your latest offers.
      responses:
        '200':
          description: Successfully created or updated the message QR code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QrCodeResponse'
              examples:
                created_qr_code_with_image:
                  summary: Newly created QR code with image
                  value:
                    code: ANED2T5QRU7HG1
                    prefilled_message: Hi! I'm interested in your products. Can you help me?
                    deep_link_url: https://wa.me/message/ANED2T5QRU7HG1
                    qr_image_url: https://scontent-iad3-2.xx.fbcdn.net/m1/v/t6/An-psFmLBls2NFXnhhkSVqwIHEqCTQoNKTLxxlOeci0Wbsukd2RLiwZalHrXwqT5RTFSzOhyw6OLvJJO0itaQtJI1BS2WkNcV67wR3GNx7ZX1tFSNCbpo1e6KPptKF1GbVGzmUfkgSPX?ccb=10-5&oh=00_AfAOAr6oRA2OKV_Ur3GUh4em57sACxUkfhXHsObiFrxOsA&oe=64DCCEF6&_nc_sid=5a413f
                updated_qr_code:
                  summary: Updated existing QR code
                  value:
                    code: WOMVT6TJ2BP7A1
                    prefilled_message: Hello! I'd like to know more about your latest offers.
                    deep_link_url: https://wa.me/message/WOMVT6TJ2BP7A1
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid prefilled_message length. Maximum 140 characters allowed
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to manage QR codes for this phone number
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - Phone number ID does not exist or QR code not found for update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Phone number not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Too many QR code operations. Please try again later
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
    ContentType:
      name: Content-Type
      in: header
      description: Media type of the request body
      required: true
      schema:
        type: string
        enum:
        - application/json
        - application/x-www-form-urlencoded
        - multipart/form-data
        default: application/json
        example: application/json
  schemas:
    CreateQrCodeRequest:
      type: object
      description: Request payload for creating a new message QR code
      required:
      - prefilled_message
      properties:
        prefilled_message:
          type: string
          description: Pre-filled message text (max 140 characters) that appears in customer chat
          maxLength: 140
          example: Hi! I'm interested in your products. Can you help me?
        generate_qr_image:
          type: string
          description: QR image format. When specified, response includes qr_image_url
          enum:
          - PNG
          - SVG
          example: SVG
    QrCodeResponse:
      type: object
      description: Response containing QR code details after creation or update
      required:
      - code
      - prefilled_message
      - deep_link_url
      properties:
        code:
          type: string
          description: 'Unique 14-character identifier for the QR code. This code is used

            for future updates or deletions.

            '
          pattern: ^[A-Z2-7]{14}$
          example: ANED2T5QRU7HG1
        prefilled_message:
          type: string
          description: 'The pre-filled message text associated with this QR code.

            This text appears when customers use the QR code.

            '
          example: Hi! I'm interested in your products. Can you help me?
        deep_link_url:
          type: string
          format: uri
          description: 'WhatsApp deep link URL that can be used directly without QR code scanning.

            Customers can click this link to start a conversation with the pre-filled message.

            '
          example: https://wa.me/message/ANED2T5QRU7HG1
        qr_image_url:
          type: string
          format: uri
          description: 'URL to download the QR code image. Only present if generate_qr_image

            parameter was specified in the request. Image format matches the requested format.

            '
          example: https://scontent-iad3-2.xx.fbcdn.net/m1/v/t6/An-psFmLBls2NFXnhhkSVqwIHEqCTQoNKTLxxlOeci0Wbsukd2RLiwZalHrXwqT5RTFSzOhyw6OLvJJO0itaQtJI1BS2WkNcV67wR3GNx7ZX1tFSNCbpo1e6KPptKF1GbVGzmUfkgSPX?ccb=10-5&oh=00_AfAOAr6oRA2OKV_Ur3GUh4em57sACxUkfhXHsObiFrxOsA&oe=64DCCEF6&_nc_sid=5a413f
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    QrCodeDetails:
      type: object
      description: Complete details of a message QR code
      required:
      - code
      - prefilled_message
      - deep_link_url
      properties:
        code:
          type: string
          description: Unique 14-character QR code identifier
          pattern: ^[A-Z2-7]{14}$
          example: ANED2T5QRU7HG1
        prefilled_message:
          type: string
          description: Pre-filled message text that appears in customer chat
          example: Hi! I'm interested in your products. Can you help me?
        deep_link_url:
          type: string
          format: uri
          description: WhatsApp deep link URL for direct conversation initiation
          example: https://wa.me/message/ANED2T5QRU7HG1
        creation_time:
          type: integer
          description: Unix timestamp when QR code was created (first-party apps only)
          example: 1672531200
        qr_image_url:
          type: string
          format: uri
          description: QR code image download URL (when format specified in fields)
          example: https://scontent-iad3-1.xx.fbcdn.net/m1/v/t6/An-H7T8OyTqO07lcRGHlKteuPMKDnx07nua3dGb4i560bVxDscweOV4KoKD_4wCDFoHR_C5LyVjxQISKPxwora1bbFhUEo2nA19ZPLBUVoQSmV12l1x-nuu312jKty-5rmojmde_a0g?ccb=10-5&oh=00_AfASq_vjojFza_9A-HDeRgHM3wZ8yjNprpYBjNKOn8RkSg&oe=64550A9E&_nc_sid=f36290
    QrCodeList:
      type: object
      description: List of message QR codes with pagination information
      required:
      - data
      properties:
        data:
          type: array
          description: Array of QR code objects
          items:
            $ref: '#/components/schemas/QrCodeDetails'
        paging:
          type: object
          description: 'Pagination information for navigating through large result sets.

            Contains cursors for accessing previous and next pages of results.

            '
          properties:
            cursors:
              type: object
              properties:
                before:
                  type: string
                  description: Cursor for accessing the previous page of results
                  example: MTYwNDYxNzIwMA==
                after:
                  type: string
                  description: Cursor for accessing the next page of results
                  example: MTYwNDYxNzIwMQ==
            previous:
              type: string
              format: uri
              description: URL for the previous page of results
              example: https://graph.facebook.com/v23.0/1234567890123456/message_qrdls?before=MTYwNDYxNzIwMA==
            next:
              type: string
              format: uri
              description: URL for the next page of results
              example: https://graph.facebook.com/v23.0/1234567890123456/message_qrdls?after=MTYwNDYxNzIwMQ==
    UpdateQrCodeRequest:
      type: object
      description: Request payload for updating an existing message QR code
      required:
      - code
      - prefilled_message
      properties:
        code:
          type: string
          description: 14-character QR code identifier to update
          pattern: ^[A-Z2-7]{14}$
          minLength: 14
          maxLength: 14
          example: ANED2T5QRU7HG1
        prefilled_message:
          type: string
          description: New pre-filled message text (max 140 characters)
          maxLength: 140
          example: Hello! I'd like to know more about your latest offers.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '