This API endpoint allows you to block one or more WhatsApp users from sending messages to your WhatsApp Business application. Blocked users will not be able to send messages, and your app will not receive any incoming messages from them. This is useful for preventing spam, harassment, or unwanted communication. Use the unblock endpoint to restore messaging for previously blocked users.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
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.
Request Parameters
| Key | Description | Value | Data type | Required/Optional | Constraints |
|---|---|---|---|---|---|
| Authorization | Access Token for the application | {{PARTNER_APP_TOKEN}} | String | Required | Should be a valid Partner App Access Token |
| appId | App ID to fetch the access token | {{APP_ID}} | String | Required |
|
| 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 | Required | The phone number or WhatsApp ID to be blocked. |
Sample Request
curl --location 'https://partner.gupshup.io/partner/app/{{APP_ID}}/user/block' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
"messaging_product": "whatsapp",
"block_users": [
{
"user": "<PHONE_NUMBER>"
}
]
}'Sample Response
{
"block_users":
{
"added_users":
[
{
"input": "919163805873",
"wa_id": "919163805873"
}
]
},
"messaging_product": "whatsapp",
"status": "success"
}Status Codes
| Status Code | Response | Comments |
|---|---|---|
| Success | ||
| 200 | { "block_users": {"added_users":[{"input": "919163805873","wa_id": "919163805873"}] | |
| Error | ||
| 400 | { "messaging_product": "whatsapp", "block_users": {"added_users": [{"input": "<PHONE_NUMBER> or <WA_ID>","wa_id": "<WA_ID>"},{"input": "<PHONE_NUMBER> or <WA_ID>", |