Block WhatsApp User Numbers

POST Method

The Block WhatsApp User Numbers API allows you to programmatically block one or more WhatsApp user mobile numbers, preventing them from sending incoming messages and stopping you from sending outgoing messages to these numbers.

📘
Notes:

Once you block the WhatsApp user's mobile number, that user will no longer be able to send messages to your business phone number.

Once you block the WhatsApp user's mobile number, you will not be able to send messages to the blocked WhatsApp user's mobile number. If attempted, you will get an error from Kaleyra platform.

The blocklist is specific to each WhatsApp Business phone number configured in the Kaleyra system. If you are using multiple WhatsApp Business numbers with Kaleyra, you can block a given user’s mobile number only for one or some of your WhatsApp Business numbers. To block a user’s mobile number on one or more of your WhatsApp Business numbers, you need to call the Block WhatsApp User Numbers API separately for each WhatsApp Business number on which you want to block the user.

Limitations

You can only block end users who have messaged you in the last 24 hours.
Blocklist capacity is limited to 64,000 mobile numbers.

Prerequisites

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID. A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on Kaleyra platform.
To set up a WhatsApp account on Kaleyra platform, see Manual Signup and Embedded Signup.
An active WhatsApp plan for Business API that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.

Base URL

https://<api_domain>/v2/<SID>

📘
Note:
If you are using WhatsApp V1 version, use https://<api_domain>/v1/<SID> endpoint.

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.ap.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

API request to Block WhatsApp User Numbers

To block WhatsApp user numbers, use:
https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/block_users
endpoint with the following request method.

Request Format

The following is the request format to block WhatsApp user numbers:

curl --location --request POST 'https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/block_users' \
-H 'api-key: <api-key>' \
-H 'Content-Type: <content-type>' \
-d '{
    "messaging_product": "<messaging_product>",
    "block_users": [
        {
            "user": "<phone_number1>"
        },
        {
            "user": "<phone_number2>"
        },
        {
            "user": "<phone_number3>"
        }
    ]
}'

Sample Request Format

The following is the sample request format to block WhatsApp user numbers:

curl --location --request POST 'https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/+9194070XXXXX/block_users'\ 
-H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
-H 'Content-Type: application/json' \
-d '{
    "messaging_product": "whatsapp",
    "block_users": [
        {
            "user": "+9194070XXXXX"
        },
        {
            "user": "+919863XXXXX"
        },
        {
            "user": "+918074XXXXX"
        }
    ]
}'

URL Parameters and Headers

The following is the list of parameters and headers to block WhatsApp user numbers:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXAP16XXXXXX97IN	Yes
`api-key`	String	API key generated from Kaleyra account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/json.	Yes
`phone_number`	String	Indicates the WhatsApp Business phone number for which you want to block the users.	+9194070XXXXX	Yes

The following is the list of attributes to be used in the payload to block WhatsApp user numbers:

Parameter / Headers	Data Type	Description	Example	Mandatory?
`messaging_product`	String	The platform being used for messaging.	The only allowed value is whatsapp.	Yes
`block_users`	Array	An array of elements representing the WhatsApp user mobile numbers to be blocked.	See the specific table for details.	Yes

The following table describes the attribute used for the block_users array:

Parameter	Data Type	Description	Example	Mandatory?
`user`	String	The phone number in (E.164 format) of the WhatsApp user you want to block.	+919863XXXXX	Yes

Sample Success Response

If all the passed user mobile number are added to the blocklist, the following success message is returned with the status 200 Accepted:

{
    "code": "WA200",
    "message": "Request Processed Successfully",
    "data": {        
          "block_users": {
            "added_users": [
              {
                "input": "+9194070XXXXX",
                "wa_id": "9194070XXXXX"
              },
              {
                "input": "+919863XXXXXX",
                "wa_id": "919863XXXXXX"
              },
              {
                "input": "+91807XXXXXXX",
                "wa_id": "91807XXXXXXX"
              }
            ]
          },
        "messaging_product": "whatsapp"
          },
    "error": {}
}

Sample Failure Responses

The following are the failure responses:

WhatsApp Phone Number Check

401 Unauthorized Phone Number Status
{
    "code": "WA401",
    "message": "The phone number you're using not active",
    "data": {},
    "error": {
        "phone_number": "The phone number you're using not active"
    }
}

401 Unauthorized Phone number
{
    "code": "WA401",
    "message": "Phone number is not present or does not belong to the account.",
    "data": {},
    "error": {
        "phone_number": "Phone number is not present or does not belong to the account."
    }
}

API Key and SID validations

401 Unauthorized
{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "error": "Incorrect SID or API key."
    }
}

Payload Validations

400 Incorrect payload
{
    "code": "WA400",
    "message": "Refer to correct payload format",
    "data": {},
    "error": {
        "payload": "Incorrect payload format"
    }
}

Internal Server Errors

500 Internal Server Error
{
    "code": "WA500",
    "message": "Please try again later",
    "data": {},
    "error": {
        "error": "Internal server error"
    }
}

Errors in blocking user’s mobile numbers on Meta side

200 OK Status
{
    "code": "WA-200",
    "message": "Request Processed Successfully",
    "data": {
        "block_users": {
            "added_users": [],
            "failed_users": [
                {
                    "errors": [
                        {
                            "code": 131XXX,
                            "error_data": {
                                "details": "Failed to block due to re-engagement check failed"
                            },
                            "message": "Re-engagement check failed"
                        }
                    ],
                    "input": "+919456XXXXXX"
                }
            ]
        },
        "errors": {
            "code": 139XXX,
            "error_data": {
                "details": "Failed to block some users, see the block_users response list for details"
            },
            "message": "(#139XXX) Failed to block/unblock users",
            "type": "OAuthException"
        },
        "messaging_product": "whatsapp"
    },
    "error": {}
}

For more information on the Block Users Error Codes, see Block Users Error Codes page.

Updated 1 day ago