Skip to main content

​
WhatsApp Cloud API - Block API

Copy for LLM View as Markdown Version v23.0 The Block API allows businesses to manage blocked users on WhatsApp. Use this API to block users from sending messages to your business number, retrieve the list of blocked users, and unblock users when needed. For more information, see the Block Users Guide.

​
Base URL

| https://graph.facebook.com |

​
Endpoints

| GET | ///block_users | | POST | ///block_users | | DELETE | ///block_users |

​
GET ///block_users

Guide: Block Users Endpoint reference: GET WhatsApp Buiness Phone Number > block_users

​
Request Syntax

GET///block_users Select language cURLJavaScriptPython 
curl --request GET \
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code 200 
\{
  "Get blocked users": {
    "value": {
      "data": [\
        {\
          "messaging_product": "whatsapp",\
          "wa_id": "16505551234"\
        }\
      ],
      "paging": {
        "cursors": {
          "after": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD",
          "before": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD"
        }
      }
    }
  }
}
Header Parameters
User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of “application/json”, “application/x-www-form-urlencoded”, “multipart/form-data”·required Media type of the request body Path Parameters
Versionstring·required Phone-Number-IDstring·required Responses
Guide: Block Users Endpoint reference: GET WhatsApp Buiness Phone Number > block_users 200 Get blocked users Content Type: application/json Schema: GetBlockedUsersData Show child attributes
GetBlockedUsersData
dataarray of BlockedUser Show child attributes
data[]BlockedUser Show child attributes
messaging_productstring
wa_idstring
pagingPaging Show child attributes
cursorsPaginationCursors Show child attributes
afterstring
beforestring Select language cURLJavaScriptPython 
curl --request GET \
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
Select status code 200 
\{
  "Get blocked users": {
    "value": {
      "data": [\
        {\
          "messaging_product": "whatsapp",\
          "wa_id": "16505551234"\
        }\
      ],
      "paging": {
        "cursors": {
          "after": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD",
          "before": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD"
        }
      }
    }
  }
}

​
POST ///block_users

Guide: Block Users Endpoint reference: POST WhatsApp Buiness Phone Number > block_users

​
Request Syntax

POST///block_users Select language cURLJavaScriptPython 
curl --request POST \
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "block_users": [\
    {\
      "user": "+16505551234"\
    }\
  ],
  "messaging_product": "whatsapp"
}'
Select status code 200 
\{
  "Block user(s)": {
    "value": {
      "block_users": {
        "added_users": [\
          {\
            "input": "+16505551234",\
            "wa_id": "16505551234"\
          }\
        ]
      },
      "messaging_product": "whatsapp"
    }
  }
}
Header Parameters
User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of “application/json”, “application/x-www-form-urlencoded”, “multipart/form-data”·required Media type of the request body Path Parameters
Versionstring·required Phone-Number-IDstring·required Request BodyOptional
Content Type: application/json Schema: object Show child attributes
block_usersarray of object Show child attributes
block_users[]object Show child attributes
userstring
messaging_productstring Responses
Guide: Block Users Endpoint reference: POST WhatsApp Buiness Phone Number > block_users 200 Block user(s) Content Type: application/json Schema: BlockUsersData Show child attributes
BlockUsersData
block_usersBlockUsersResult Show child attributes
added_usersarray of BlockedUserOperation Show child attributes
added_users[]BlockedUserOperation Show child attributes
inputstring
wa_idstring
messaging_productstring Select language cURLJavaScriptPython 
curl --request POST \
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "block_users": [\
    {\
      "user": "+16505551234"\
    }\
  ],
  "messaging_product": "whatsapp"
}'
Select status code 200 
\{
  "Block user(s)": {
    "value": {
      "block_users": {
        "added_users": [\
          {\
            "input": "+16505551234",\
            "wa_id": "16505551234"\
          }\
        ]
      },
      "messaging_product": "whatsapp"
    }
  }
}

​
DELETE ///block_users

Guide: Block Users Endpoint reference: DELETE WhatsApp Buiness Phone Number > block_users

​
Request Syntax

DELETE///block_users Select language cURLJavaScriptPython 
curl --request DELETE \
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "block_users": [\
    {\
      "user": "+16505551234"\
    }\
  ],
  "messaging_product": "whatsapp"
}'
Select status code 200 
\{
  "Unblock user(s)": {
    "value": {
      "block_users": {
        "removed_users": [\
          {\
            "input": "+16505551234",\
            "wa_id": "16505551234"\
          }\
        ]
      },
      "messaging_product": "whatsapp"
    }
  }
}
Header Parameters
User-Agentstring The user agent string identifying the client software making the request. Authorizationstring·required Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token. Content-TypeOne of “application/json”, “application/x-www-form-urlencoded”, “multipart/form-data”·required Media type of the request body Path Parameters
Versionstring·required Phone-Number-IDstring·required Request BodyOptional
Content Type: application/json Schema: object Show child attributes
block_usersarray of object Show child attributes
block_users[]object Show child attributes
userstring
messaging_productstring Responses
Guide: Block Users Endpoint reference: DELETE WhatsApp Buiness Phone Number > block_users 200 Unblock user(s) Content Type: application/json Schema: UnblockUsersData Show child attributes
UnblockUsersData
block_usersUnblockUsersResult Show child attributes
removed_usersarray of BlockedUserOperation Show child attributes
removed_users[]BlockedUserOperation Show child attributes
inputstring
wa_idstring
messaging_productstring Select language cURLJavaScriptPython 
curl --request DELETE \
  --url 'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
  --header 'Authorization: Bearer <Token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "block_users": [\
    {\
      "user": "+16505551234"\
    }\
  ],
  "messaging_product": "whatsapp"
}'
Select status code 200 
\{
  "Unblock user(s)": {
    "value": {
      "block_users": {
        "removed_users": [\
          {\
            "input": "+16505551234",\
            "wa_id": "16505551234"\
          }\
        ]
      },
      "messaging_product": "whatsapp"
    }
  }
}

​
Authentication

| Scheme | Type | Location | | bearerAuth | HTTP Bearer | Header: Authorization |

​
Usage Examples

bearerAuth: Include Authorization: Bearer your-token-here in request headers

​
Global Authentication Requirements

All endpoints require: bearerAuth Did you find this page helpful? Thumbs up icon Thumbs down icon