Skip to main content

​
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

ParameterDescription
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

ParameterDescription
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:
inputString — Phone number of a WhatsApp user
wa_idString — Unique ID of a WhatsApp user
failed_users
Object		List of users failed to be blocked
Contains values of both:
inputString — Phone number of a WhatsApp user
wa_idString — 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

ParameterDescription
messaging_product
String		Required
Messaging service used for the request. Must be "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

ParameterDescription
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:
inputString — Phone number of a WhatsApp user
wa_idString — Unique ID of a WhatsApp user
failed_users
Object		List of users failed to be blocked
Contains values of both:
inputString — Phone number of a WhatsApp user
wa_idString — 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

ParameterDescription
limit
Optional		Maximum number of blocked users to fetch in the request.
after
Optional		Learn more about Paginated Results in Graph API here
before
Optional		Learn more about Paginated Results in Graph API here

​
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

ParameterDescription
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
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

CodeDescription
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 Thumbs down icon 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