Block Users API guide | Developer Documentation
Block Users API guide
Updated: Feb 23, 2026
The Block Users API enables your business to block bad actors from contacting you.
How it works
When you block a WhatsApp user, the following happens:
Errors on the API occur per-number since blocks might succeed on some numbers and fail on others.
The Block Users API is synchronous.
Limitations
Features
The API contains three endpoints:
// Block WhatsApp user numbers
POST /<PHONE_NUMBER_ID>/block_users// Unblock WhatsApp user numbers
DELETE /<PHONE_NUMBER_ID>/block_users// Get list of blocked WhatsApp user numbers
GET /<PHONE_NUMBER_ID>/block_usersBlock users
Use this endpoint to block a list of WhatsApp user numbers.
Endpoint
POST /<PHONE_NUMBER_ID>/block_usersRequest body
{
"messaging_product": "whatsapp",
"block_users": [
{
"user": "<PHONE_NUMBER> or <WA_ID>"
}
]
}
Request parameters
| Parameter | Description |
|---|---|
messaging_productString | Required Messaging service used for the request. Must be "whatsapp". |
block_usersArray | Required List of user(s) to block. Each element contains a user field. |
userstring | The phone number or WhatsApp ID you want to block. |
Response object
SUCCESS (200)
{
"messaging_product": "whatsapp",
"block_users": {
"added_users": [
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>"
}
]
}
}
Response parameters
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
block_usersObject | Contains two lists: added_users — List of successfully blocked users.failed_users — List of users that were not blocked. | ||||||
added_usersObject | List of successfully blocked users. Contains values of both:
| ||||||
failed_usersObject | List of users that were not blocked. Contains values of:
|
MIXED SUCCESS/FAILURE (400)
{
"messaging_product": "whatsapp",
"block_users": {
"added_users": [
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>"
},
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>"
},
...
],
"failed_users": [
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>", // May not be present if the number is invalid
"errors": [
{
"message": "<MESSAGE>",
"code": <CODE>,
"error_data": {
"details": "<DETAILS>"
}
}
]
}
]
},
"error": {
"message": "(#139100) Failed to block/unblock users",
"type": "OAuthException",
"code": 139100,
"error_data": {
"details": "Failed to block some users, see the block_users response list for details"
},
"fbtrace_id": "<FBTRACE_ID>"
}
}
Unblock users
Use this endpoint to unblock a list of WhatsApp user numbers.
Endpoint
DELETE /<PHONE_NUMBER_ID>/block_usersRequest body
{
"messaging_product": "whatsapp",
"block_users": [
{
"user": "<PHONE_NUMBER> or <WA_ID>"
}
]
}
Request parameters
| Parameter | Description |
|---|---|
messaging_productString | Required Messaging service used for the request. Must be "whatsapp". |
block_usersArray | Required List of user(s) to unblock. Each element contains a user field. |
userstring | The phone number or WhatsApp ID you want to unblock. |
Response object
SUCCESS (200)
{
"messaging_product": "whatsapp",
"block_users": {
"removed_users": [
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>"
}
]
}
}
Response parameters
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
block_usersObject | Contains two lists: removed_users — List of successfully unblocked users.failed_users — List of users that were not unblocked. | ||||||
removed_usersObject | List of successfully unblocked users. Contains values of both:
| ||||||
failed_usersObject | List of users that were not unblocked. Contains values of:
|
MIXED SUCCESS/FAILURE (400)
{
"messaging_product": "whatsapp",
"block_users": {
"removed_users": [
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>"
},
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>"
},
...
],
"failed_users": [
{
"input": "<PHONE_NUMBER> or <WA_ID>",
"wa_id": "<WA_ID>", // May not be present if the number is invalid
"errors": [
{
"message": "<MESSAGE>",
"code": <CODE>,
"error_data": {
"details": "<DETAILS>"
}
}
]
}
]
},
"error": {
"message": "(#139100) Failed to block/unblock users",
"type": "OAuthException",
"code": 139100,
"error_data": {
"details": "Failed to unblock some users, see the block_users response list for details"
},
"fbtrace_id": "<FBTRACE_ID>"
}
}
Get list of blocked numbers
Use this endpoint to get a list of blocked numbers on your WhatsApp Business number.
Endpoint
GET /<PHONE_NUMBER_ID>/block_usersQuery options
?limit=10&after=<AFTER_CURSOR>&before=<BEFORE_CURSOR>Query parameters
| Parameter | Description |
|---|---|
limitOptional | Maximum number of blocked users to fetch in the request. |
afterOptional | Learn more about Paginated Results in Graph API |
beforeOptional | Learn more about Paginated Results in Graph API |
Response object
SUCCESS
{
"data": [
{
"messaging_product": "whatsapp",
"wa_id": "<WA_ID>"
}
],
"paging": {
"cursors": {
"after": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD",
"before": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD"
}
}
}
Response parameters
| Parameter | Description |
|---|---|
dataArray | List of blocked users. Each element contains messaging_product and wa_id fields. |
messaging_productString | Required Messaging service used for the request. Must be "whatsapp". |
wa_idString | Unique ID of a WhatsApp user |
pagingObject | Learn more about Paginated Results in Graph API. |
Error codes
ERROR
{
"messaging_product": "whatsapp",
"error": {
"message": "(#139102) Blocklist concurrent update",
"type": "OAuthException",
"code": 139102,
"error_data": {
"details": "Blocklist was updated during retrieval - retry with offset 0"
},
"fbtrace_id": "<FBTRACE_ID>"
}
}
| Code | Description |
|---|---|
139100Failed to block/unblock some users | Bulk blocking failed to block some or all of the users. |
139101Blocklist limit reached | The blocklist has reached its 64,000 user limit. |
139102Blocklist concurrent update | Occurs when the blocklist is updated while performing a pagination request and version_id does not match. |
139103Internal error | Internal error, please try again. |
130429Rate Limit Hit | Occurs when either: |
131021Self Block | Failed to block self phone number. |
131047Re-engagement required | Occurs if the business has not received a message from that number in the last 24 hours. This error will also be returned if the number is an invalid WhatsApp user. |
No comments to display
No comments to display