Block Users

Block, unblock, and list WhatsApp users on a business number with Meta's Block Users API through the Dualhook Runtime API: the 24-hour rule, per-user results, error codes, and Coexistence notes.

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

OperationMethod and path
Block usersPOST /v25.0/<PHONE_NUMBER_ID>/block_users
Unblock usersDELETE /v25.0/<PHONE_NUMBER_ID>/block_users
List blocked usersGET /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.

CodeMeaningWhat to do
139100Some or all users failedCheck failed_users for each user's own error.
131047The user has not messaged you in the last 24 hours, or is not a valid WhatsApp userBlock only users who wrote in the last 24 hours.
139101The blocklist is full (64,000 users)Unblock users you no longer need to block.
139102The blocklist changed during a paginated readStart the listing again.
139103Internal errorRetry the request.
130429Too many users in one request, or too many requests in a short timeSend fewer users per request and slow down.
131021You tried to block your own numberRemove it from the list.
100A BSUID sent in userSend 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.

Related

Browse more docsStart Free Trial