WhatsApp Phone Number Registration API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  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: Phone Number Registration
  description: APIs for registering and managing WhatsApp Business phone numbers
paths:
  /{Version}/{Phone-Number-ID}/register:
    post:
      summary: Register WhatsApp Business Phone Number
      description: 'Register a WhatsApp Business phone number for messaging capabilities and enable

        two-step verification. This is a required step before sending messages through

        the WhatsApp Business Cloud API.


        **Registration Process:**

        1. Phone number must be in UNVERIFIED status

        2. Provide a 6-digit PIN for two-step verification

        3. Optionally provide backup data for account migration

        4. Registration activates messaging capabilities


        **Migration Support:**

        For migrating from on-premises WhatsApp Business API, include backup data

        with password and encrypted account information.


        **Rate Limiting:**

        Registration attempts are rate-limited to prevent abuse. Standard Graph API

        rate limits apply with additional restrictions for registration endpoints.


        **Security Requirements:**

        - Two-step verification is mandatory for all registered numbers

        - PIN must be securely stored and managed by the business

        - Registration enables webhook delivery and message sending capabilities'
      operationId: registerWhatsAppBusinessPhoneNumber
      tags:
      - Phone Number Registration
      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 ID of the phone number to register. This ID is provided when the phone number

          is added to your WhatsApp Business Account and can be found in WhatsApp Manager.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        description: Registration request payload with PIN and optional migration data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsAppBusinessPhoneNumberRegistrationRequest'
            examples:
              basic_registration:
                summary: Basic phone number registration
                description: Register a new phone number with two-step verification
                value:
                  messaging_product: whatsapp
                  pin: '123456'
              migration_registration:
                summary: Account migration registration
                description: Register phone number with backup data for migration
                value:
                  messaging_product: whatsapp
                  pin: '123456'
                  backup:
                    password: YOUR_BACKUP_PASSWORD
                    data: YOUR_BACKUP_DATA
              advanced_registration:
                summary: Registration with data localization settings
                description: Register with specific data localization settings
                value:
                  messaging_product: whatsapp
                  pin: '123456'
                  data_localization_region: AE
      responses:
        '200':
          description: Successfully registered WhatsApp Business phone number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessPhoneNumberRegistrationResponse'
              examples:
                successful_registration:
                  summary: Successful registration
                  value:
                    success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid PIN format. PIN must be exactly 6 digits
                  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 register 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
        '422':
          description: Unprocessable Entity - Phone number cannot be registered in current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Phone number is already registered or in invalid state for registration
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Registration rate limit exceeded
                  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 during registration. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  schemas:
    WhatsAppBusinessPhoneNumberRegistrationRequest:
      type: object
      description: Request payload for registering a WhatsApp Business phone number
      required:
      - messaging_product
      - pin
      properties:
        messaging_product:
          type: string
          description: Must be 'whatsapp' to indicate WhatsApp Business messaging product
          enum:
          - whatsapp
          example: whatsapp
        pin:
          type: string
          description: 6-digit PIN for two-step verification setup
          pattern: ^[0-9]{6}$
          minLength: 6
          maxLength: 6
          example: '123456'
        backup:
          $ref: '#/components/schemas/WhatsAppBusinessAccountBackup'
        data_localization_region:
          $ref: '#/components/schemas/WhatsAppDataLocalizationRegion'
        meta_store_retention_minutes:
          type: integer
          description: Message retention period in minutes (deprecated in v21+)
          minimum: 60
          maximum: 60
          example: 60
    WhatsAppBusinessPhoneNumberRegistrationResponse:
      type: object
      description: Response from phone number registration request
      required:
      - success
      properties:
        success:
          type: boolean
          description: Indicates whether the registration was successful
          example: true
    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
    WhatsAppBusinessAccountBackup:
      type: object
      description: Backup data for migrating existing WhatsApp Business accounts
      properties:
        password:
          type: string
          description: Backup password for account migration
          example: YOUR_BACKUP_PASSWORD
        data:
          type: string
          description: Encrypted backup data for account migration
          example: YOUR_BACKUP_DATA
    WhatsAppDataLocalizationRegion:
      type: string
      description: Data localization region for message storage (deprecated in v21+)
      enum:
      - AE
      - AU
      - BH
      - BR
      - CA
      - CH
      - DE
      - GB
      - ID
      - IN
      - JP
      - KR
      - SG
      - ZA
      example: AE
  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
  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

        '