WhatsApp

WhatsApp Block Users API

The Block Users API from WhatsApp — 1 operation(s) for block users.

GitHub OpenAPI

Operations 3

GET /{Version}/{Phone-Number-ID}/block_users Get blocked users #
POST /{Version}/{Phone-Number-ID}/block_users Block user(s) #
DELETE /{Version}/{Phone-Number-ID}/block_users Unblock user(s) #

Documentation

📖
Documentation
https://developers.facebook.com/documentation/business-messaging/whatsapp/overview

Specifications

⚙
OpenAPI
https://artifacts.apis.io/whatsapp/openapi/whatsapp-block-users-api-openapi.yml

SDKs

📦
GitHubRepository
https://github.com/meta/openapi

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/whatsapp/json-schema/whatsapp-call-request-payload-schema.json
📊
JSONSchema
https://artifacts.apis.io/whatsapp/json-schema/whatsapp-whats-app-business-account-schema.json
📊
JSONSchema
https://artifacts.apis.io/whatsapp/json-schema/whatsapp-whats-app-business-profile-node-schema.json
📊
JSONSchema
https://artifacts.apis.io/whatsapp/json-schema/whatsapp-phone-number-info-schema.json
📊
JSONSchema
https://artifacts.apis.io/whatsapp/json-schema/whatsapp-call-permission-check-response-payload-schema.json
📊
JSONSchema
https://artifacts.apis.io/whatsapp/json-schema/whatsapp-whats-app-account-number-schema.json

Other Resources

🔗
PostmanCollection
https://raw.githubusercontent.com/WhatsApp/WhatsApp-Flows-Tools/main/postman/v1/whatsapp-cloud-api.postman_collection.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/whatsapp:whatsapp-block-users-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

whatsapp-block-users-api-openapi.yml Raw ↑ 
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: Block Users
paths:
  /{Version}/{Phone-Number-ID}/block_users:
    parameters:
    - name: Version
      in: path
      required: true
      schema:
        type: string
    - name: Phone-Number-ID
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Block Users
      summary: Get blocked users
      description: '- Guide: Block Users


        - Endpoint reference: GET WhatsApp Buiness Phone Number > block_users'
      operationId: getBlockedUsers
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      responses:
        '200':
          $ref: '#/components/responses/GetBlockedUsersResponse'
      security:
      - bearerAuth: []
    post:
      tags:
      - Block Users
      summary: Block user(s)
      description: '- Guide: Block Users


        - Endpoint reference: POST WhatsApp Buiness Phone Number > block_users'
      operationId: blockUserS
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                block_users:
                  type: array
                  items:
                    type: object
                    properties:
                      user:
                        type: string
                        example: '+16505551234'
                  example:
                  - user: '+16505551234'
                messaging_product:
                  type: string
                  example: whatsapp
            examples:
              Block user(s):
                value:
                  block_users:
                  - user: '+16505551234'
                  messaging_product: whatsapp
      responses:
        '200':
          $ref: '#/components/responses/BlockUsersResponse'
      security:
      - bearerAuth: []
    delete:
      tags:
      - Block Users
      summary: Unblock user(s)
      description: '- Guide: Block Users


        - Endpoint reference: DELETE WhatsApp Buiness Phone Number > block_users'
      operationId: unblockUserS
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                block_users:
                  type: array
                  items:
                    type: object
                    properties:
                      user:
                        type: string
                        example: '+16505551234'
                  example:
                  - user: '+16505551234'
                messaging_product:
                  type: string
                  example: whatsapp
            examples:
              Unblock user(s):
                value:
                  block_users:
                  - user: '+16505551234'
                  messaging_product: whatsapp
      responses:
        '200':
          $ref: '#/components/responses/UnblockUsersResponse'
      security:
      - bearerAuth: []
components:
  schemas:
    Paging:
      type: object
      properties:
        cursors:
          $ref: '#/components/schemas/PaginationCursors'
    GetBlockedUsersData:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlockedUser'
          example:
          - messaging_product: whatsapp
            wa_id: '16505551234'
        paging:
          $ref: '#/components/schemas/Paging'
    BlockUsersData:
      type: object
      properties:
        block_users:
          $ref: '#/components/schemas/BlockUsersResult'
        messaging_product:
          type: string
          example: whatsapp
    UnblockUsersResult:
      type: object
      properties:
        removed_users:
          type: array
          items:
            $ref: '#/components/schemas/BlockedUserOperation'
          example:
          - input: '+16505551234'
            wa_id: '16505551234'
    BlockedUser:
      type: object
      properties:
        messaging_product:
          type: string
          example: whatsapp
        wa_id:
          type: string
          example: '16505551234'
    BlockedUserOperation:
      type: object
      properties:
        input:
          type: string
          example: '+16505551234'
        wa_id:
          type: string
          example: '16505551234'
    UnblockUsersData:
      type: object
      properties:
        block_users:
          $ref: '#/components/schemas/UnblockUsersResult'
        messaging_product:
          type: string
          example: whatsapp
    BlockUsersResult:
      type: object
      properties:
        added_users:
          type: array
          items:
            $ref: '#/components/schemas/BlockedUserOperation'
          example:
          - input: '+16505551234'
            wa_id: '16505551234'
    PaginationCursors:
      type: object
      properties:
        after:
          type: string
          example: eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD
        before:
          type: string
          example: eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD
  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
  responses:
    BlockUsersResponse:
      description: Block user(s)
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/Access-Control-Allow-Origin'
        Alt-Svc:
          $ref: '#/components/headers/Alt-Svc'
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Connection:
          $ref: '#/components/headers/Connection'
        Content-Length:
          $ref: '#/components/headers/Content-Length'
        Date:
          $ref: '#/components/headers/Date'
        Expires:
          $ref: '#/components/headers/Expires'
        Pragma:
          $ref: '#/components/headers/Pragma'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Vary:
          $ref: '#/components/headers/Vary'
        X-FB-Connection-Quality:
          $ref: '#/components/headers/X-FB-Connection-Quality'
        X-FB-Debug:
          $ref: '#/components/headers/X-FB-Debug'
        facebook-api-version:
          $ref: '#/components/headers/facebook-api-version'
        x-business-use-case-usage:
          $ref: '#/components/headers/x-business-use-case-usage'
        x-fb-request-id:
          $ref: '#/components/headers/x-fb-request-id'
        x-fb-rev:
          $ref: '#/components/headers/x-fb-rev'
        x-fb-trace-id:
          $ref: '#/components/headers/x-fb-trace-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BlockUsersData'
          examples:
            Block user(s):
              value:
                block_users:
                  added_users:
                  - input: '+16505551234'
                    wa_id: '16505551234'
                messaging_product: whatsapp
    GetBlockedUsersResponse:
      description: Get blocked users
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/Access-Control-Allow-Origin'
        Alt-Svc:
          $ref: '#/components/headers/Alt-Svc'
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Connection:
          $ref: '#/components/headers/Connection'
        Content-Length:
          $ref: '#/components/headers/Content-Length'
        Date:
          $ref: '#/components/headers/Date'
        ETag:
          $ref: '#/components/headers/ETag'
        Expires:
          $ref: '#/components/headers/Expires'
        Pragma:
          $ref: '#/components/headers/Pragma'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Vary:
          $ref: '#/components/headers/Vary'
        X-FB-Debug:
          $ref: '#/components/headers/X-FB-Debug'
        facebook-api-version:
          $ref: '#/components/headers/facebook-api-version'
        x-business-use-case-usage:
          $ref: '#/components/headers/x-business-use-case-usage'
        x-fb-request-id:
          $ref: '#/components/headers/x-fb-request-id'
        x-fb-rev:
          $ref: '#/components/headers/x-fb-rev'
        x-fb-trace-id:
          $ref: '#/components/headers/x-fb-trace-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetBlockedUsersData'
          examples:
            Get blocked users:
              value:
                data:
                - messaging_product: whatsapp
                  wa_id: '16505551234'
                paging:
                  cursors:
                    after: eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD
                    before: eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD
    UnblockUsersResponse:
      description: Unblock user(s)
      headers:
        Access-Control-Allow-Origin:
          $ref: '#/components/headers/Access-Control-Allow-Origin'
        Alt-Svc:
          $ref: '#/components/headers/Alt-Svc'
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
        Connection:
          $ref: '#/components/headers/Connection'
        Content-Length:
          $ref: '#/components/headers/Content-Length'
        Date:
          $ref: '#/components/headers/Date'
        Expires:
          $ref: '#/components/headers/Expires'
        Pragma:
          $ref: '#/components/headers/Pragma'
        Strict-Transport-Security:
          $ref: '#/components/headers/Strict-Transport-Security'
        Vary:
          $ref: '#/components/headers/Vary'
        X-FB-Connection-Quality:
          $ref: '#/components/headers/X-FB-Connection-Quality'
        X-FB-Debug:
          $ref: '#/components/headers/X-FB-Debug'
        facebook-api-version:
          $ref: '#/components/headers/facebook-api-version'
        x-business-use-case-usage:
          $ref: '#/components/headers/x-business-use-case-usage'
        x-fb-request-id:
          $ref: '#/components/headers/x-fb-request-id'
        x-fb-rev:
          $ref: '#/components/headers/x-fb-rev'
        x-fb-trace-id:
          $ref: '#/components/headers/x-fb-trace-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnblockUsersData'
          examples:
            Unblock user(s):
              value:
                block_users:
                  removed_users:
                  - input: '+16505551234'
                    wa_id: '16505551234'
                messaging_product: whatsapp
  headers:
    Content-Length:
      schema:
        type: string
        example: '25'
      description: Size of the response body in bytes
    x-fb-request-id:
      schema:
        type: string
        example: AGaOBl2yM-g8gdON-dhzl5y
      description: Unique identifier for the request for debugging purposes
    Expires:
      schema:
        type: string
        example: Sat, 01 Jan 2000 00:00:00 GMT
      description: Expiration date for cached responses
    Date:
      schema:
        type: string
        example: Fri, 24 Jan 2025 00:48:41 GMT
      description: Date and time when the response was generated
    Access-Control-Allow-Origin:
      schema:
        type: string
        example: '*'
      description: CORS policy allowing access from any origin
    x-fb-trace-id:
      schema:
        type: string
        example: E7riEe9OW2e
      description: Facebook trace identifier for request tracking
    Vary:
      schema:
        type: string
        example: Accept-Encoding
      description: Headers that affect caching and content negotiation
    x-business-use-case-usage:
      schema:
        type: string
        example: '{"102290129340398":[{"type":"whatsapp_business_management","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0},{"type":"whatsapp","call_count":1,"total_cputime":1,"total_time":1,"estimated_time_to_regain_access":0}]}'
      description: Business use case usage metrics and rate limiting information
    Connection:
      schema:
        type: string
        example: keep-alive
      description: Connection management directive
    X-FB-Debug:
      schema:
        type: string
        example: 52zkUgodnaVRhbBE+3RiGz6TnmjmDEGunwYd+vKSc4synE+Xii//dy6twB/7yKgOJiMUuV0OF248UAZ1qL3v0A==
      description: Facebook debug information for troubleshooting
    facebook-api-version:
      schema:
        type: string
        example: v22.0
      description: Facebook Graph API version used for the request
    Strict-Transport-Security:
      schema:
        type: string
        example: max-age=15552000; preload
      description: HSTS header enforcing HTTPS connections
    X-FB-Connection-Quality:
      schema:
        type: string
        example: EXCELLENT; q=0.9, rtt=7, rtx=0, c=10, mss=1380, tbw=372, tp=-1, tpl=-1, uplat=527, ullat=0
      description: Facebook connection quality metrics
    Pragma:
      schema:
        type: string
        example: no-cache
      description: Legacy cache control directive
    Alt-Svc:
      schema:
        type: string
        example: h3=":443"; ma=86400
      description: Alternative service advertisement for HTTP/3
    Cache-Control:
      schema:
        type: string
        example: private, no-cache, no-store, must-revalidate
      description: Cache control directives for the response
    ETag:
      schema:
        type: string
        example: '"eb11a43a8f1e633acc57540de90158ed9ede1eb6"'
      description: Entity tag for caching and conditional requests
    x-fb-rev:
      schema:
        type: string
        example: '1019544279'
      description: Facebook internal revision number
  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

        '