WhatsApp Cloud API

Block Users API

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 /<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",
  // List of WhatsApp user numbers to be blocked
  "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

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": "<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 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": "<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>"
      },
      {
        "input": "<PHONE_NUMBER> or <WA_ID>",
        "wa_id": "<WA_ID>"
      },
      ...
        "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": [
     {
       // List of WhatsApp user numbers to be unblocked
       "user": "<PHONE_NUMBER> or <WA_ID>"
     }  
   ]
}

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": "<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 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": "<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>"
      },
      {
        "input": "<PHONE_NUMBER> or <WA_ID>",
        "wa_id": "<WA_ID>"
      }
      ...
        "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>"
  }
}

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 Parameters

?limit=10, // Optional
&after=<AFTER_CURSOR>,   // Optional
&before=<BEFORE_CURSOR>  // 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": "<PHONE_NUMBER> or <WA_ID>",
        "wa_id": "<WA_ID>"
      } 
      ]
    }
  ],
  "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": "<FBTRACE_ID>"
  } 
}

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:

  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.