> ## Documentation Index > Fetch the complete documentation index at: https://whatsapp-docs.kap.so/llms.txt > Use this file to discover all available pages before exploring further. # Block users # Block Users API Updated: Oct 27, 2025 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: The user cannot contact your business or see that you are online. Your business cannot message the user. If you do, you will encounter an error. You cannot use this API to block another WhatsApp Business Errors on the API occur per-number since blocks might be successful on some numbers and not others. The Block Users API is synchronous. ## Limitations You can only block users that have messaged your business in the last 24 hours. 64k blocklist limit ## Features The API contains 3 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_users ``` ## Block Users Use this endpoint to block a list of WhatsApp user numbers. ### Endpoint ``` POST /<PHONE_NUMBER_ID>/block_users ``` ### Request Body ``` \{   "messaging_product": "whatsapp",   // List of WhatsApp user numbers to be blocked   "block_users": [\     {\       "user": "<PHONE_NUMBER> or <WA_ID>"\     }\   ] } ``` ### Request Parameters | Parameter | Description | | --------------------------------- | ------------------------------------------------------------------------------------ | | `messaging_product`
*String* | *Required*
Messaging service used for the request. Must be `"whatsapp"`. | | `block_users`
*Object* | *Required*
List of user(s) to block.
Each element contains a `user` field. | | `user`
*string* | The phone number or WhatsApp ID to be blocked. | ### 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_users`
*Object* | Contains two lists:
`added-users` — List of successfully blocked users.
`failed_users` — List of users failed to be blocked. | | `added_users`
*Object* | List of successfully blocked users. | Contains values of both: | | | | ------- | ------------------------------------------ | | `input` | *String* — Phone number of a WhatsApp user | | | | | | ---------------------------- | --------------------------------------- | - | | `wa_id` | *String* — Unique ID of a WhatsApp user | | | `failed_users`
*Object* | List of users failed to be blocked | | Contains values of both: | | | | ------- | ------------------------------------------ | | `input` | *String* — Phone number of a WhatsApp user | | | | | | ------- | --------------------------------------- | - | | `wa_id` | *String* — Unique ID of a WhatsApp user | | ``` 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>"\       },\       {\         "input": "<PHONE_NUMBER> or <WA_ID>",\         "wa_id": "<WA_ID>"\       },\       ...\         "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_users ``` ### Request Body ``` \{   "messaging_product": "whatsapp",   "block_users": [\      {\        // List of WhatsApp user numbers to be unblocked\        "user": "<PHONE_NUMBER> or <WA_ID>"\      }\    ] } ``` ### Request Parameters | Parameter | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messaging_product`
*String* | *Required*
Messaging service used for the request. Must be `"whatsapp"`.
[Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#whatsapp-cloud-api) only. | | `block_users`
*Object* | *Required*
List of user(s) to block.
Each element contains a `user` field. | | `user`
*string* | The phone number or WhatsApp ID to be blocked. | ### 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_users`
*Object* | Contains two lists:
`added-users` — List of successfully blocked users.
`failed_users` — List of users failed to be blocked. | | `added_users`
*Object* | List of successfully blocked users. | Contains values of both: | | | | ------- | ------------------------------------------ | | `input` | *String* — Phone number of a WhatsApp user | | | | | | ---------------------------- | --------------------------------------- | - | | `wa_id` | *String* — Unique ID of a WhatsApp user | | | `failed_users`
*Object* | List of users failed to be blocked | | Contains values of both: | | | | ------- | ------------------------------------------ | | `input` | *String* — Phone number of a WhatsApp user | | | | | | ------- | --------------------------------------- | - | | `wa_id` | *String* — Unique ID of a WhatsApp user | | ``` 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>"\       },\       {\         "input": "<PHONE_NUMBER> or <WA_ID>",\         "wa_id": "<WA_ID>"\       }\       ...\         "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>"   } } ``` ## 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_users ``` ### Query Parameters ``` ?limit=10, // Optional &after=<AFTER_CURSOR>, // Optional &before=<BEFORE_CURSOR> // Optional ``` ### Response Parameters | Parameter | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------- | | `limit`
*Optional* | Maximum number of blocked users to fetch in the request. | | `after`
*Optional* | Learn more about [Paginated Results in Graph API here](https://developers.facebook.com/docs/graph-api/results) | | `before`
*Optional* | Learn more about [Paginated Results in Graph API here](https://developers.facebook.com/docs/graph-api/results) | ### Response Object ``` SUCCESS \{   "data": [\     {\       "block_users": [\       {\         "input": "<PHONE_NUMBER> or <WA_ID>",\         "wa_id": "<WA_ID>"\       }\       ]\     }\   ],   "paging": {     "cursors": {       "after": "MTAxNTExOTQ1MjAwNzI5NDE=",       "before": "NDMyNzQyODI3OTQw"     },     "previous": "https://graph.facebook.com/{version}/{phone-number-id}/block_users?limit=10&before=NDMyNzQyODI3OTQw",     "next": "https://graph.facebook.com/{version}/{phone-number-id}/block_users?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="   } } ``` ### Response Parameters | Parameter | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------- | | `block_users`
*Object* | *Required*
List of user(s) to block.
Each element contains a `user` field. | | `wa_id`
*String* | Phone number of the blocked user | | `paging`
*Object* | Learn more about [Paginated Results in Graph API here](https://developers.facebook.com/docs/graph-api/results) | ``` ERROR \{   "messaging_product": "whatsapp",   "error": {     "message": "(#135002) Blocklist concurrent update",     "type": "OAuthException",     "code": 139102,     "error_data": {         "messaging_product": "whatsapp",         "details": "Blocklist was updated during retrieval - retry with offset 0"     },     "fbtrace_id": "<FBTRACE_ID>"   } } ``` ## Error Codes | Code | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `139100`
Failed to block/unblock some users | Bulk blocking failed to block some or all of the users. | | `139101`
Blocklist limit reached | The blocklist limit is reached when the 64k limit is met. | | `139102`
Blocklist concurrent update | Occurs when the block list is updated while performing a pagination request and `version_id` does not match. | | `139103`
Internal error | Internal error, please try again. | | `130429`
Rate Limit Hit | Occurs when either:
Too many numbers are in the request itself.
Or, too many requests are made over a short period of time. | | `131021`
Self Block | Failed to block self phone number. | | `131047`
Re-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. | Did you find this page helpful? ![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) ![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) ON THIS PAGE How it Works Limitations Features Block Users Endpoint Request Body Request Parameters Response Object Response Parameters Unblock Users Endpoint Request Body Request Parameters Response Object Response Parameters Get List of Blocked Numbers Endpoint Query Parameters Response Parameters Response Object Response Parameters Error Codes ***