Skip to main content

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:
    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.
    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

      You can only block users that have messaged your business in the last 24 hours.You cannot use this API to block another WhatsApp Business account.The blocklist has a 64,000 user limit.

      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_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",
      "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
      Array
      Required
      List of user(s) to block.
      Each element contains a user field.
      user
      string
      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_users
      Object
      Contains two lists:
        added_users — List of successfully blocked users.failed_users — List of users that were not 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 that were not blocked.
          Contains values of:
            input
            String — Phone number of a WhatsApp user
            wa_id
            String — Unique ID of a WhatsApp user (may not be present if the number is invalid)
            errors
            Array — Error details for the 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>", // 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_users
            Request body
            {
            "messaging_product": "whatsapp",
            "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
            Array
            Required
            List of user(s) to unblock.
            Each element contains a user field.
            user
            string
            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_users
            Object
            Contains two lists:
              removed_users — List of successfully unblocked users.failed_users — List of users that were not unblocked.
              removed_users
              Object
              List of successfully unblocked 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 that were not unblocked.
                Contains values of:
                  input
                  String — Phone number of a WhatsApp user
                  wa_id
                  String — Unique ID of a WhatsApp user (may not be present if the number is invalid)
                  errors
                  Array — Error details for the user
                  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_users
                  Query options
                  ?limit=10&after=<AFTER_CURSOR>&before=<BEFORE_CURSOR>
                  Query parameters
                  
Parameter

Description

                  limit
                  Optional
                  Maximum number of blocked users to fetch in the request.
                  after
                  Optional
                  before
                  Optional
                  Response object
                  SUCCESS

                  {
                  "data": [
                      {
                  "messaging_product": "whatsapp",
                  "wa_id": "<WA_ID>"
                      }
                    ],
                  "paging": {
                  "cursors": {
                  "after": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD",
                  "before": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3Mzc2Nzk2ODgzODM1ODQifQZDZD"
                      }
                    }
                  }
                  Response parameters
                  
Parameter

Description

                  data
                  Array
                  List of blocked users.
                  Each element contains messaging_product and wa_id fields.
                  messaging_product
                  String
                  Required
                  Messaging service used for the request. Must be "whatsapp".
                  wa_id
                  String
                  Unique ID of a WhatsApp user
                  paging
                  Object
                  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 




                  

                  139100
                  

                  Failed to block/unblock some users
                  


                  

                  Bulk blocking failed to block some or all of the users.
                  



                  

                  139101
                  

                  Blocklist limit reached
                  


                  

                  The blocklist has reached its 64,000 user limit.
                  



                  

                  139102
                  

                  Blocklist concurrent update
                  


                  

                  Occurs when the blocklist 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.
                    
    
                            
                    
    
                    

            
                    
        
                    
    
                    

    
                    

    
    
                    
        
                    
             Back to top