WhatsApp Business Platform
WhatsApp Business Platform
Resources

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:
  1. added_users — List of successfully blocked users.
  2. 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:
  1. removed_users — List of successfully unblocked users.
  2. 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
Learn more about Paginated Results in Graph API
before
Optional
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
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
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
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:
  1. Too many numbers are in the request itself.
  2. 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