What Blocking Does
Meta's Block Users API keeps a blocklist per business phone number. When you block a WhatsApp user:
- The user cannot contact your business or see that you are online.
- Your business cannot message the user. Sends to them fail with 130403.
With Dualhook you call the API on api.dualhook.com with the connection's dh_live_ key. The paths and payloads are Meta's, on the connection's own <PHONE_NUMBER_ID>:
| Operation | Method and path |
|---|---|
| Block users | POST /v25.0/<PHONE_NUMBER_ID>/block_users |
| Unblock users | DELETE /v25.0/<PHONE_NUMBER_ID>/block_users |
| List blocked users | GET /v25.0/<PHONE_NUMBER_ID>/block_users |
Limitations
- You can only block or unblock users who messaged your business in the last 24 hours.
- A request takes at most 1,000 users.
- The blocklist holds at most 64,000 users.
- Results come back synchronously in the API response, per user. Keep your own record of who you blocked and why.
Block Users
Name each user by phone number in user, or by BSUID or parent BSUID in user_id. An entry can carry both; Meta then uses user. A BSUID sent in user returns error 100, and Dualhook rejects an entry with neither field before it reaches Meta.
curl -X POST "https://api.dualhook.com/v25.0/<PHONE_NUMBER_ID>/block_users" \
-H "Authorization: Bearer <DH_LIVE_KEY>" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"block_users": [
{"user": "+16505551234"},
{"user_id": "US.13491208655302741918"}
]
}'
{
"messaging_product": "whatsapp",
"block_users": {
"added_users": [
{"input": "+16505551234", "wa_id": "16505551234"},
{"input": "US.13491208655302741918", "user_id": "US.13491208655302741918"}
]
}
}
input echoes what you sent. wa_id may be left out when you named the user by user_id, and user_id is returned only when you named the user by user_id alone. A user's phone number and wa_id do not always match.
Unblock Users
Unblocking is a DELETE with the same JSON body. The response lists removed_users instead of added_users.
curl -X DELETE "https://api.dualhook.com/v25.0/<PHONE_NUMBER_ID>/block_users" \
-H "Authorization: Bearer <DH_LIVE_KEY>" \
-H "Content-Type: application/json" \
-d '{"messaging_product":"whatsapp","block_users":[{"user":"+16505551234"}]}'
An unblock fails with 131047 when the user has not messaged you in the last 24 hours, the same rule as blocking. If an automated block was a mistake, undo it quickly.
List Blocked Users
curl "https://api.dualhook.com/v25.0/<PHONE_NUMBER_ID>/block_users?limit=25" \
-H "Authorization: Bearer <DH_LIVE_KEY>"
{
"data": [
{"messaging_product": "whatsapp", "wa_id": "16505551234"},
{"messaging_product": "whatsapp", "user_id": "US.13491208655302741918"}
],
"paging": {
"cursors": {"after": "<SAFE_CURSOR>", "before": "<SAFE_CURSOR>"}
}
}
Each entry carries wa_id when the user was blocked by phone number, or user_id when blocked by BSUID. limit is 1 to 100, and Dualhook sends 25 when you leave it out. Pass one cursor back as after or before to page; see Pagination. Error 139102 means the blocklist changed while you were paging, so start the listing again.
Partial Failures and Errors
Results are per user. When some users fail, the response lists them in failed_users next to added_users or removed_users, and Meta adds a top-level error with code 139100:
{
"messaging_product": "whatsapp",
"block_users": {
"added_users": [{"input": "+16505551234", "wa_id": "16505551234"}],
"failed_users": [
{
"input": "+14155559876",
"errors": [
{
"message": "Re-engagement required",
"code": 131047,
"error_data": {"details": "User has not messaged in the last 24 hours"}
}
]
}
]
},
"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>"
}
}
Read failed_users before treating the call as failed: the users in added_users are blocked.
| Code | Meaning | What to do |
|---|---|---|
139100 | Some or all users failed | Check failed_users for each user's own error. |
131047 | The user has not messaged you in the last 24 hours, or is not a valid WhatsApp user | Block only users who wrote in the last 24 hours. |
139101 | The blocklist is full (64,000 users) | Unblock users you no longer need to block. |
139102 | The blocklist changed during a paginated read | Start the listing again. |
139103 | Internal error | Retry the request. |
130429 | Too many users in one request, or too many requests in a short time | Send fewer users per request and slow down. |
131021 | You tried to block your own number | Remove it from the list. |
100 | A BSUID sent in user | Send BSUIDs in user_id. |
Blocking Automatically
The 24-hour rule fits automation that reacts to inbound messages: a bot or AI that reads a new conversation, for example a lead from a Click-to-WhatsApp ad, can block the sender while the window is open.
- Block one user, or a small batch, per request as messages arrive. Dualhook allows 10 block or unblock requests per minute per connection, each with up to 1,000 users, separate from the limit on template and profile changes.
- Log every automated block with the reason, so a person can review it.
- Avoid broad rules that can catch real customers. Blocked users cannot message you, and an unblock can fail once their last message is more than 24 hours old.
Coexistence Numbers
The Block Users API works on Coexistence numbers. Meta does not document how it interacts with the WhatsApp Business app, but in customer testing a user blocked through the API also shows as blocked in the app. To block a contact who has not written in the last 24 hours, block them in the app on the phone instead.
Dualhook Boundary
Block, unblock, and list calls go through the Runtime API without Dualhook storing or logging who was blocked. Dualhook checks that the path's phone number ID belongs to the key's connection, validates the request, and relays only the documented response fields: per-user input, wa_id, user_id and errors, plus Meta's top-level error. Dualhook does not block or unblock anyone on your behalf and keeps no copy of your blocklist.