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 /&lt;PHONE_NUMBER_ID&gt;/block_users

// Unblock WhatsApp user numbers
DELETE /&lt;PHONE_NUMBER_ID&gt;/block_users

// Get list of blocked WhatsApp user numbers
GET /&lt;PHONE_NUMBER_ID&gt;/block_users

Block Users

Use this endpoint to block a list of WhatsApp user numbers.

Endpoint

POST /&lt;PHONE_NUMBER_ID&gt;/block_users

Request Body

\{
  "messaging_product": "whatsapp",
  // List of WhatsApp user numbers to be blocked
  "block_users": [\
    {\
      "user": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;"\
    }\
  ]
}

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": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      }\
    ]
  }
}

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": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      ...\
    ],
    "failed_users": [\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      ...\
        "errors": [{\
          "message": "&lt;MESSAGE&gt;",\
          "code": "&lt;CODE&gt;",\
          "error_data": {\
            "details": "&lt;DETAILS&gt;""\
          }]\
        }\
      }\
    ]
  },
  "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": "&lt;FBTRACE_ID&gt;"
  }
}

Unblock Users

Use this endpoint to unblock a list of WhatsApp user numbers.

Endpoint

DELETE /&lt;PHONE_NUMBER_ID&gt;/block_users

Request Body

\{
  "messaging_product": "whatsapp",
  "block_users": [\
     {\
       // List of WhatsApp user numbers to be unblocked\
       "user": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;"\
     }\
   ]
}

Request Parameters

Parameter	Description
`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": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      }\
    ]
  }
}

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": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      ...\
    ],
    "failed_users": [\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      },\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      }\
      ...\
        "errors": [{\
          "message": "&lt;MESSAGE&gt;",\
          "code": "&lt;CODE&gt;",\
          "error_data": {\
            "details": "&lt;DETAILS&gt;""\
          }]\
        }\
      }\
    ]
  },
  "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": "&lt;FBTRACE_ID&gt;"
  }
}

Get List of Blocked Numbers

Use this endpoint to get a list of blocked numbers on your WhatsApp Business number.

Endpoint

GET /&lt;PHONE_NUMBER_ID&gt;/block_users

Query Parameters

?limit=10, // Optional
&after=&lt;AFTER_CURSOR&gt;,   // Optional
&before=&lt;BEFORE_CURSOR&gt;  // 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
`before` Optional	Learn more about Paginated Results in Graph API here

Response Object

SUCCESS

\{
  "data": [\
    {\
      "block_users": [\
      {\
        "input": "&lt;PHONE_NUMBER&gt; or &lt;WA_ID&gt;",\
        "wa_id": "&lt;WA_ID&gt;"\
      }\
      ]\
    }\
  ],
  "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

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": "&lt;FBTRACE_ID&gt;"
  }
}

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

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

​Block Users API

​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

Block Users API

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