Block and unblock users

Last update: 6 hours ago by Irais Aguirre

Integration summary
Base URL: https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services
Token: admin token, in the Authorization: Bearer {{admin-token}} header (how to generate it)
Endpoints on this page:
POST /v1/block_users/{{waba_id}}/{{phone_number_id}}: Block users
PUT /v1/block_users/{{waba_id}}/{{phone_number_id}}: Unblock users

Block and unblock WhatsApp users for a phone number in your WABA. You can identify each user by their phone number or BSUID.

Block users

Request

Block users request:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/block_users/{{waba_id}}/{{phone_number_id}}
Method	POST
Type	application/json

Headers

Block users headers:

Name	Description	Type	Requirements
Content-Type	application/json	String	Required
Authorization	Admin token. See Generate authentication token.	String	Required

Parameters

Block users parameters:

Name	Description	Type	Requirements
waba_id	WhatsApp Business Account ID.	String	Required
phone_number_id	ID of the phone number that blocks the users.	String	Required

Body

Block users body fields:

Name	Description	Type	Requirements
block_users	List of users to block.	List of user objects	Required

User object

Name	Description	Type	Requirements
user	The user's phone number or business-scoped user ID (BSUID).	String	Required. Can't be empty.

Example

Complete Block users example:

curl --location 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/block_users/{{waba_id}}/{{phone_number_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{admin-token}}' \
--data '{
    "block_users": [
        {
            "user": "521550123456"
        },
        {
            "user": "US.13491208655302741918"
        }
    ]
}'

Response

Block users response:

If the request succeeds, the service returns HTTP 201.

Name	Description	Type
messaging_product	Always `"whatsapp"`. Included to match Meta Cloud API responses.	String
block_users	Object with the users that were blocked and those that weren't.	Object
errors	Top-level error returned by Meta when the request failed as a whole (as opposed to per-user failures, which appear under `block_users.failed_users`). Omitted on a fully successful response.	Object

Block users object

Name	Description	Type
added_users	List of blocked users.	List of added users objects
failed_users	List of users that couldn't be blocked.	List of failed users objects

Added users object

Name	Description	Type
input	Identifier sent in the request.	String
wa_id	WhatsApp ID resolved by Meta.	String

{
    "messaging_product": "whatsapp",
    "block_users": {
        "added_users": [
            {
                "input": "2721520198",
                "wa_id": "5212721520198"
            }
        ],
        "failed_users": [
            {
                "input": "2721520160",
                "errors": [
                    {
                        "code": 131047,
                        "message": "Re-engagement check failed",
                        "error_data": {
                            "details": "Failed to block due to re-engagement check failed"
                        }
                    }
                ]
            }
        ]
    }
}

Unblock users

Request

Unblock users request:


URL	https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/block_users/{{waba_id}}/{{phone_number_id}}
Method	PUT
Type	application/json

Headers

Unblock users headers:

Name	Description	Type	Requirements
Content-Type	application/json	String	Required
Authorization	Admin token. See Generate authentication token.	String	Required

Parameters

Unblock users parameters:

Name	Description	Type	Requirements
waba_id	WhatsApp Business Account ID.	String	Required
phone_number_id	ID of the phone number that unblocks the users.	String	Required

Body

Unblock users body fields:

Name	Description	Type	Requirements
block_users	List of users to unblock.	List of user objects	Required

Example

Complete Unblock users example:

curl --location --request PUT 'https://{{url}}/whatsapp-bsp-admin-ext-endpoint-ws/services/v1/block_users/{{waba_id}}/{{phone_number_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{admin-token}}' \
--data '{
    "block_users": [
        {
            "user": "2721520198"
        }
    ]
}'

Response

Unblock users response:

If the request succeeds, the service returns HTTP 200.

Name	Description	Type
block_users	Object with the users that were unblocked and those that weren't.	Object

Block users unblock object

Name	Description	Type
removed_users	List of unblocked users.	List of removed users objects
failed_users	List of users that couldn't be unblocked.	List of failed users objects

Removed users object

Name	Description	Type
input	Identifier sent in the request.	String
wa_id	WhatsApp ID resolved by Meta.	String

{
    "block_users": {
        "removed_users": [
            {
                "input": "2721520198",
                "wa_id": "5212721520198"
            }
        ],
        "failed_users": [
            {
                "input": "US.13491208655302741918",
                "errors": [
                    {
                        "code": 131047,
                        "message": "Re-engagement check failed",
                        "error_data": {
                            "details": "Failed to block due to re-engagement check failed"
                        }
                    }
                ]
            }
        ]
    }
}

Failed users object

Used for both blocking and unblocking.

Name	Description	Type
input	Identifier sent in the request.	String
errors	List of errors that prevented the operation.	List of errors objects

Errors object

Name	Description	Type
code	Error code.	Number
message	Error message.	String
error_data	Error details.	Object

Error data object

Name	Description	Type
details	Detailed reason why the user couldn't be blocked or unblocked.	String

WhatsApp — Previous

Block users

List blocked users