Appearance
WhatsApp Cloud API - Block API
Version
v23.0v24.0v25.0
Copy for LLM
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 | /{Version}/{Phone-Number-ID}/block_users | | POST | /{Version}/{Phone-Number-ID}/block_users | | DELETE | /{Version}/{Phone-Number-ID}/block_users |
GET /{Version}/{Phone-Number-ID}/block_users
- Guide: Block Users
- Endpoint reference: GET WhatsApp Buiness Phone Number > block_users
Request Syntax
GET /{Version}/{Phone-Number-ID}/block_users
Try it
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 /{Version}/{Phone-Number-ID}/block_users
- Guide: Block Users
- Endpoint reference: POST WhatsApp Buiness Phone Number > block_users
Request Syntax
POST /{Version}/{Phone-Number-ID}/block_users
Try it
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 /{Version}/{Phone-Number-ID}/block_users
- Guide: Block Users
- Endpoint reference: DELETE WhatsApp Buiness Phone Number > block_users
Request Syntax
DELETE /{Version}/{Phone-Number-ID}/block_users
Try it
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