WhatsApp WhatsApp Business Profiles 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: WhatsApp Business Profiles
  description: APIs for managing WhatsApp Business Profile details and configuration
paths:
  /{Version}/{WhatsApp-Business-Profile-ID}:
    get:
      summary: Get WhatsApp Business Profile Details
      description: 'Retrieve comprehensive details about a WhatsApp Business Profile, including business information,

        contact details, and profile configuration.


        **Use Cases:**

        - Retrieve business profile information and metadata

        - Verify profile configuration and contact details

        - Check profile status and business information

        - Validate profile state before business operations


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.


        **Caching:**

        Profile details can be cached for moderate periods, but business information may change

        occasionally. Implement appropriate cache invalidation strategies.'
      operationId: getWhatsAppBusinessProfileDetails
      tags:
      - WhatsApp Business Profiles
      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: WhatsApp-Business-Profile-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Profile ID. This ID is provided when the profile is created

          and can be found in your WhatsApp Business Manager or through business management APIs.

          '
        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. If not specified,

          default fields will be returned (id and any available profile fields).

          Available fields: id, account_name, description, email, about, address, vertical, websites, profile_picture_url, messaging_product

          '
        schema:
          type: string
        example: id,account_name,description,email,about,vertical
      responses:
        '200':
          description: Successfully retrieved WhatsApp Business Profile details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessProfileNode'
              examples:
                complete_profile:
                  summary: Complete business profile with all details
                  value:
                    id: '1234567890123456'
                    account_name: E-commerce Business Account
                    description: Leading e-commerce platform for quality products
                    email: contact@business-example.com
                    about: Quality products delivered worldwide
                    address: 123 Business Street, Commerce City, CC 12345
                    vertical: RETAIL
                    websites:
                    - https://www.business-example.com
                    - https://shop.business-example.com
                    profile_picture_url: https://pps.whatsapp.net/v/profile-picture-url
                    messaging_product: whatsapp
                minimal_profile:
                  summary: Minimal business profile with required fields only
                  value:
                    id: '2345678901234567'
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: whatsapp_business_profile_id must be a valid numeric string'
                  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 access this WhatsApp Business Profile
                  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 - WhatsApp Business Profile ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Profile not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The requested fields are not available for this profile
                  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: Application request limit reached
                  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: Update WhatsApp Business Profile
      description: 'Update the WhatsApp Business Profile information such as business description, email, address,

        and other profile details. This operation corresponds to the GraphWhatsAppBusinessProfilePost functionality.


        **Use Cases:**

        - Update business profile information and metadata

        - Modify contact details and business description

        - Change business vertical classification

        - Update website URLs and profile picture

        - Maintain current business profile information


        **Profile Picture Upload:**

        It is recommended to use the Resumable Upload API to obtain an upload ID, then use this

        upload ID to obtain the picture handle for the `profile_picture_handle` field.


        **Rate Limiting:**

        Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.'
      operationId: updateWhatsAppBusinessProfile
      tags:
      - WhatsApp Business Profiles
      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: WhatsApp-Business-Profile-ID
        in: path
        required: true
        description: 'Your WhatsApp Business Profile ID. This ID is provided when the profile is created

          and can be found in your WhatsApp Business Manager or through business management APIs.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsAppBusinessProfileUpdateRequest'
            examples:
              complete_update:
                summary: Complete profile update with all fields
                value:
                  messaging_product: whatsapp
                  account_name: Updated E-commerce Business
                  description: Updated leading e-commerce platform for premium products
                  email: updated-contact@business-example.com
                  about: Premium products delivered worldwide with excellent service
                  address: 456 Updated Business Avenue, Commerce City, CC 54321
                  vertical: RETAIL
                  websites:
                  - https://www.updated-business-example.com
                  - https://shop.updated-business-example.com
                  profile_picture_handle: 4:VGVzdC5wbmc=:aW1hZ2UvanBlZw==:ARat4Mt-L09JON3f30SmDkdyPSuyBkDDYiB4TFXuXISjdgHoNp2b7j882_9Jzr2tPrdKxi92UygyVzTivJiOvmebMpZ6MIjTik3gTyI3ZCQAgQ:e:1659995302:2022308451254161:636685196:ARZf1ftR5N6-qSLtklU
              minimal_update:
                summary: Minimal profile update with required fields only
                value:
                  messaging_product: whatsapp
                  description: Updated customer service business
                  email: updated-support@service-example.com
      responses:
        '200':
          description: Successfully updated WhatsApp Business Profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppBusinessProfileUpdateResponse'
              examples:
                successful_update:
                  summary: Successful profile update response
                  value:
                    id: '1234567890123456'
                    success: true
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: messaging_product is required'
                  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 update this WhatsApp Business Profile
                  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 modify this resource
        '404':
          description: Not Found - WhatsApp Business Profile ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Profile not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The provided profile picture handle is invalid or expired
                  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: Application request limit reached
                  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:
  schemas:
    WhatsAppBusinessVertical:
      type: string
      description: The industry type of the business
      enum:
      - OTHER
      - AUTO
      - BEAUTY
      - APPAREL
      - EDU
      - ENTERTAIN
      - EVENT_PLAN
      - FINANCE
      - GROCERY
      - GOVT
      - HOTEL
      - HEALTH
      - NONPROFIT
      - PROF_SERVICES
      - RETAIL
      - TRAVEL
      - RESTAURANT
      - ALCOHOL
      - ONLINE_GAMBLING
      - PHYSICAL_GAMBLING
      - OTC_DRUGS
      example: RESTAURANT
    WhatsAppBusinessProfileUpdateResponse:
      type: object
      description: Response after updating business profile
      properties:
        success:
          type: boolean
          description: Indicates whether the update 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
    WhatsAppBusinessProfileUpdateRequest:
      type: object
      description: Request payload for updating WhatsApp Business Profile
      required:
      - messaging_product
      properties:
        messaging_product:
          type: string
          description: The messaging service used for the request
          enum:
          - whatsapp
          example: whatsapp
        about:
          type: string
          description: The text to display in business profile's About section
          minLength: 1
          maxLength: 139
          example: Welcome to our business! We provide excellent service.
        address:
          type: string
          description: The address of the business
          maxLength: 256
          example: 123 Business Street, City, State 12345
        description:
          type: string
          description: Description of the business
          maxLength: 256
          example: We are a leading provider of quality products and services.
        email:
          type: string
          description: The contact email address of the business
          format: email
          maxLength: 128
          example: contact@business.com
        profile_picture_handle:
          type: string
          description: The handle of the profile picture generated from Resumable Upload API
          example: 4:VGVzdC5wbmc=:aW1hZ2UvanBlZw==:ARat4Mt-L09JON3f30SmDkdyPSuyBkDDYiB4TFXuXISjdgHoNp2b7j882_9Jzr2tPrdKxi92UygyVzTivJiOvmebMpZ6MIjTik3gTyI3ZCQAgQ:e:1659995302:2022308451254161:636685196:ARZf1ftR5N6-qSLtklU
        websites:
          type: array
          description: URLs associated with the business
          maxItems: 2
          items:
            type: string
            format: uri
            maxLength: 256
          example:
          - https://www.business.com
          - https://www.facebook.com/business
        vertical:
          $ref: '#/components/schemas/WhatsAppBusinessVertical'
    WhatsAppBusinessProfileNode:
      type: object
      description: WhatsApp Business Profile node details and configuration
      required:
      - id
      properties:
        id:
          type: string
          description: Unique identifier for the WhatsApp Business Profile
          example: '1234567890123456'
        account_name:
          type: string
          description: Name of the business account
          minLength: 1
          maxLength: 75
          example: E-commerce Business Account
        description:
          type: string
          description: Business description text
          minLength: 1
          maxLength: 256
          example: Leading e-commerce platform for quality products
        email:
          type: string
          format: email
          description: Contact email address of the business
          maxLength: 128
          example: contact@business-example.com
        about:
          type: string
          description: About section text for the business profile
          minLength: 1
          maxLength: 139
          example: Quality products delivered worldwide
        address:
          type: string
          description: Physical address of the business
          maxLength: 256
          example: 123 Business Street, Commerce City, CC 12345
        vertical:
          $ref: '#/components/schemas/WhatsAppBusinessVertical'
        websites:
          type: array
          description: List of website URLs associated with the business
          maxItems: 2
          items:
            type: string
            format: uri
            maxLength: 256
            example: https://www.business-example.com
          example:
          - https://www.business-example.com
          - https://shop.business-example.com
        profile_picture_url:
          type: string
          format: uri
          description: URL of the business profile picture
          example: https://pps.whatsapp.net/v/profile-picture-url
        profile_picture_handle:
          type: string
          description: Handle of the profile picture for upload operations
          example: 4:VGVzdC5wbmc=:aW1hZ2UvanBlZw==:ARat4Mt-L09JON3f30SmDkdyPSuyBkDDYiB4TFXuXISjdgHoNp2b7j882_9Jzr2tPrdKxi92UygyVzTivJiOvmebMpZ6MIjTik3gTyI3ZCQAgQ:e:1659995302:2022308451254161:636685196:ARZf1ftR5N6-qSLtklU
        messaging_product:
          type: string
          description: The messaging service used
          enum:
          - whatsapp
          example: whatsapp
  parameters:
    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
    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...
  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

        '