Skip to content

A glossary story9 chapters · 6 min read

Block Users API

Cloud API endpoints that let a business block, unblock and list WhatsApp users who abuse its number, so they can no longer message it or be messaged by it.

Also called: block_users endpoint · WhatsApp block user API · Business blocklist

Reviewed

Follow along

Block an abusive sender and read what comes back

2 / 2
POSThttps://graph.facebook.com/v26.0/106540352242922/block_users

POST 200 in 700 ms

Request

3 headers · body
POST /v26.0/106540352242922/block_users HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
{
"messaging_product": "whatsapp",
"block_users": [
{
"user": "+919812345678"
}
]
}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json
{
"messaging_product": "whatsapp",
"block_users": {
"added_users": [
{
"input": "+919812345678",
"wa_id": "919812345678"
}
]
}
}
Try another response
A block request for one user who messaged in the last hour. Press Send for the clean result, then switch to a mixed result, a full blocklist or a request that was too large.

Response: 200 OK after 700 ms.

Chapter 1 · The scenario

Example: A night-time flood on a Bhopal coaching institute's number

A Bhopal coaching institute's admissions number starts receiving dozens of abusive messages a minute from one number at 1 am, each one triggering a chatbot reply. The integration's abuse rule (more than 20 flagged messages in five minutes) pauses the bot for that contact and calls POST /block_users; added_users returns the wa_id, and a ticket records the reason for the morning team. The same morning, staff ask to block a number that sent offensive messages a week earlier. That call fails in failed_users with error 131047 because the user has not messaged in 24 hours, so the team adds the number to its suppression list instead. Three weeks later a parent explains that a child had misused their phone; a supervisor reviews the log and sends DELETE, and the number appears in removed_users.

— A night-time flood on a Bhopal coaching institute's number

Chapter 2 · What is the Block Users API?

The Block Users API is a set of WhatsApp Cloud API endpoints that let a business block WhatsApp users who abuse its number, unblock them later and list who is currently blocked. All three actions use one path on the business phone number, /{PHONE_NUMBER_ID}/block_users: POST blocks, DELETE unblocks and GET lists. It gives an API-driven support desk or chatbot the control a person has when they block a contact on their own phone, applied to a business number that may be answered by software and many agents at once.

A block works in both directions. The blocked user can no longer contact the business or see that it is online, and the business can no longer message that user; a send through the messages endpoint returns an error. Meta attaches one important condition: you can only block users who have messaged your business in the last 24 hours, which is the same moment the 24-hour customer service window is open. The API is a response to abuse inside a live conversation, not a tool for pre-loading lists of numbers. Each request carries a block_users array of up to 1,000 { "user": "+91…" } entries, and the response reports every number separately in added_users (or removed_users when unblocking) and failed_users, each with its wa_id.

Blocking is easy to confuse with two other things. An opt-out is the customer choosing to stop receiving marketing; you honour it by adding them to a suppression list, and they can still message you for help. Block rate measures the opposite direction, customers blocking your business, which feeds your quality rating. The Block Users API is the business's own decision to cut contact with a specific abusive user, and it should be used for harassment, spam floods and threats, never as an unsubscribe mechanism.

Key takeaways

  • The Block Users API blocks, unblocks and lists users on one business phone number through /{PHONE_NUMBER_ID}/block_users.
  • You can only block a user who has messaged your business in the last 24 hours; anyone else fails with error 131047.
  • Each request takes up to 1,000 users, and the blocklist holds at most 64,000; error 139101 means it is full.
  • A blocked user cannot message you or see that you are online, and your business cannot message them until you unblock.
  • Blocking is the business's decision about abuse; an opt-out is the customer's decision to stop receiving messages.

Chapter 3 · How it unfolds

How does the Block Users API work?

  1. Decide what counts as abuse

    Write a short policy (threats, slurs, spam floods, impersonation) and decide who may block: an agent from the inbox, a supervisor, or an automated rule with a human review queue.

  2. Block while the window is open

    POST { "messaging_product": "whatsapp", "block_users": [{ "user": "+919812345678" }] } to /{PHONE_NUMBER_ID}/block_users within 24 hours of the user's last message. Use the number in the same form you would send to.

  3. Read every user's result

    Successes come back in block_users.added_users with the input and wa_id; failures in failed_users, each with its own errors[]. If any user failed, the response also carries a top-level error 139100.

  4. Update your own systems

    Mark the contact as blocked in your CRM and campaign tools so broadcasts and bots skip them, and record who blocked them, when and why.

  5. Review and unblock

    List the blocklist with GET, using cursor-based pagination (limit, after, before). To unblock, send DELETE with the same body; successes come back in removed_users.

Chapter 4 · In code

The Block Users API in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/block_users" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "block_users": [ { "user": "+919812345678" } ]
  }'
 
# Unblock: same body, DELETE method
curl -X DELETE "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/block_users" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "block_users": [ { "user": "+919812345678" } ] }'
 
# List the blocklist, 100 at a time
curl "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/block_users?limit=100" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

One path, three methods. Pass paging.cursors.after back as after= to read the next page.

Chapter 5 · Where it goes wrong

Common mistakes with the Block Users API

  • Trying to block numbers in advance

    A list of known spam numbers, or a user who abused you last week, cannot be blocked: anyone who has not messaged in 24 hours fails with 131047. Put those numbers on your own suppression list and block if they write again.

  • Treating the response as all or nothing

    Blocks succeed or fail per user, and a mixed result still comes with a top-level 139100. Read added_users and failed_users every time and act on each user's own error code.

  • Using blocking as an unsubscribe

    A customer who replied STOP to offers may still need to ask about an order or a refund. Honour opt-outs by suppressing marketing, and keep blocking for genuine abuse.

  • Forgetting other numbers and systems

    The blocklist belongs to the phone number ID you call, so a user blocked on your support number can still reach a sales number. Block on each number they abuse, and sync the status to your CRM and campaign tools.

  • Paging a list that is changing

    If someone blocks or unblocks while you page through the list, the next page can fail with 139102. Restart the listing from the first page rather than stitching mismatched pages together.

Chapter 6 · The facts

The Block Users API: key facts and limits

Endpoint/{PHONE_NUMBER_ID}/block_users
MethodsPOST block · DELETE unblock · GET list
Who can be blockedUsers who messaged you in the last 24 hours
Users per requestUp to 1,000
Blocklist sizeUp to 64,000 users (error 139101 when full)
Partial failureTop-level error 139100, details per user in failed_users
Other errors131047 not messaged in 24 h · 131021 own number · 130429 too many
EffectNo messages either way; user cannot see you online

Chapter 7 · Why it matters

Why does the Block Users API matter?

One abusive sender can flood a chatbot with hundreds of messages a night, burn agent time, trigger automated replies that have been charged as service messages at ₹0.145 each in India since 1 October 2026, and expose staff to harassment. Without an API, someone has to notice the conversation and act by hand, often after the 24-hour chance to block has passed. Wiring blocking into your inbox or abuse rules lets the right person, or a well-tested rule, stop the problem while the conversation is still live, with an audit trail and a clean path to unblock.

Chapter 8 · Block Users API FAQs

Block Users API FAQs

Can a business block a customer on the WhatsApp Business API?+
Yes, with the Block Users API, but only if that user has messaged the business in the last 24 hours. Send POST to /{PHONE_NUMBER_ID}/block_users with the user's number; the response lists each user as added or failed.
What happens when a business blocks a user on WhatsApp?+
Contact stops in both directions. The user cannot message the business or see that it is online, and the business cannot message the user until it unblocks them with a DELETE call to the same endpoint.
Why does blocking a user fail with error 131047?+
Because the user has not messaged your business in the last 24 hours, or the number is not a valid WhatsApp user. Retrying will not help; add the number to your suppression list and block it if the user writes again.
Is blocking a user the same as an opt-out?+
No. An opt-out is the customer asking to stop receiving messages, and they can still contact you. A block is the business ending contact with an abusive user, in both directions.
How many users can a WhatsApp business number block?+
Up to 64,000 users on the blocklist, added at most 1,000 per request. When the list is full, further blocks fail with error 139101 until you unblock someone.

Chapter 9 · What good teams do

Best practices for the Block Users API

  • Put a Block button in the agent inbox that calls the API directly, so action happens while the 24-hour window is open.
  • Require a reason code for every block and keep an audit log with masked phone numbers.
  • Pause chatbot replies to a flagged contact first; it stops the flood even before a human confirms the block.
  • Retry 139103 (an internal error) with backoff, but never retry 131047 — the condition will not change.
  • Review the blocklist every quarter and unblock anyone blocked by mistake.

See InfiQ pricing

* Per-message rates for India, ex-GST: marketing, utility and authentication effective 1 July 2026; service messages ₹0.145 since 1 October 2026 (they were ₹0 until 30 September 2026). Volume commitments earn discounts — final rate is confirmed on your account; applicable GST extra. Rates for other countries differ (see the international rate table on /pricing).

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms