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

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