Skip to main content

WhatsApp Cloud API - Block API | Developer Documentation

WhatsApp Cloud API - Block API

Copy for LLM
Version
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

Request Syntax

GET /{Version}/{Phone-Number-ID}/block_users
Try it
Select language
curl--requestGET \
--url'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
--header'Authorization: Bearer <Token>' \
--header'Content-Type: application/json' \
--data'{}'
Select status code
{
"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
Select language
Phone-Number-IDstring·required
Responses
Select status code
200
Get blocked users
Select language
Select status code
Content Type: application/json
Schema: GetBlockedUsersData
Show child attributes
GetBlockedUsersData
dataarray of BlockedUser
Show child attributes
data[]BlockedUser
Show child attributes
messaging_productstring

Authentication

Scheme
Type
Location
wa_id
stringbearerAuth
pagingPaging
Show child attributes
cursorsPaginationCursors
Show child attributes
afterstring
beforestring
Select language
curl--requestGET \
--url'https://graph.facebook.com/{Version}/{Phone-Number-ID}/block_users' \
--header'Authorization: Bearer <Token>' \
--header'Content-Type: application/json' \
--data'{}'
Select status code
{
"Get blocked users": {
"value": {
"data": [
        {
"messaging_product": "whatsapp",
"wa_id": "16505551234"
        }
      ],
"paging": {
"cursors": {
"after": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD",
"before": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD"
        }
      }
    }
  }
}

POST /{Version}/{Phone-Number-ID}/block_users

Request Syntax

POST /{Version}/{Phone-Number-ID}/block_users
Try it
Select language
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
{
"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
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
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
{
"Block user(s)": {
"value": {
"block_users": {
"added_users": [
          {
"input": "+16505551234",
"wa_id": "16505551234"
          }
        ]
      },
"messaging_product": "whatsapp"
    }
  }
}

DELETE /{Version}/{Phone-Number-ID}/block_users

Request Syntax

DELETE /{Version}/{Phone-Number-ID}/block_users
Try it
Select language
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
{
"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
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
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
{
"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
Back to top