Block Users - nxtele/nxcloud-doc-en GitHub Wiki

Block Users

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
/api/wa/createBlockUsers

// Unblock WhatsApp user numbers
/api/wa/deleteBlockUsers

// Get list of blocked WhatsApp user numbers
/api/wa/getBlockUsers

Authentication Mechanism

Please refer to the following link for authentication rules: API Interface Call Convention

Request Parameters

header Parameters：

Parameter Name Type Required Example Description
accessKey String Yes fme2na3kdi3ki User identity identifier
ts String Yes 1655710885431 Current timestamp of the request (in milliseconds). The maximum allowed time difference is 60 seconds on the server side.
bizType String Yes 2 WhatsApp business type, fixed value "2"
action String Yes mt WhatsApp business operation, fixed value "mt"
sign String Yes 6e9506557d1f289501d333ee2c365826 API input parameter signature, signature algorithm

Block Users

Use this endpoint to block a list of WhatsApp user numbers.

API

  • URL：https://api2.nxcloud.com/api/wa/createBlockUsers
  • Method：POST
  • Content-Type：application/json
  • Requires authentication: Yes

Request Body

Parameter Name Type Required Example Description
appkey String Yes Appkey of the NxCloud WhatsApp application
business_phone String Yes 86158xxxx1795 WhatsApp number , including country code. e.g., 86158xxxx1795
messaging_product String Yes whatsapp Channel for sending messages, must be "whatsapp" when sending WhatsApp messages
block_users User Object Yes List of user(s) to block.Each element contains a user field.

User

Parameter Name Type Required Example Description
user String Yes 861xxx The phone number or WhatsApp ID to be blocked.

Request Body example

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "852xxx",
    "block_users": [
        {
            "user": "86133xxx"
        },
        {
            "user": "86144xxx"
        }
    ]
}

Response Parameters

Parameter Name Description
block_usersObject Contains two lists: added-users — List of successfully blocked users. failed_users — List of users failed to be blocked.
added_usersObject List of successfully blocked users.Contains values of both: input
failed_usersObject List of users failed to be blocked. Contains values of both: input

Response SUCCESS

{
    "code": 0,
    "data": {
        "block_users": {
            "added_users": [
                {
                    "input": "86133xxx",
                    "wa_id": "86133xxx"
                },
                {
                    "input": "86144xxx",
                    "wa_id": "86144xxx"
                }
            ]
        },
        "messaging_product": "whatsapp"
    },
    "message": "请求成功"
}

Response MIXED SUCCESS/FAILURE

{
    "code": 0,
    "data": {
        "block_users": {
            "failed_users": [
                {
                    "input": "861xxx",
                    "errors": [
                        {
                            "code": 131047,
                            "message": "Re-engagement check failed",
                            "error_data": {
                                "details": "Failed to block due to re-engagement check failed"
                            }
                        }
                    ]
                }
            ],
            "added_users": [
                {
                    "input": "86133xxx",
                    "wa_id": "86133xxx"
                }
            ]
        },
        "messaging_product": "whatsapp"
    },
    "message": "请求成功"
}

Unblock Users

Use this endpoint to unblock a list of WhatsApp user numbers.

API

  • URL：https://api2.nxcloud.com/api/wa/deleteBlockUsers
  • Method：POST
  • Content-Type：application/json
  • Requires authentication: Yes

Request Body

Parameter Name Type Required Example Description
appkey String Yes Appkey of the NxCloud WhatsApp application
business_phone String Yes 86158xxxx1795 WhatsApp number , including country code. e.g., 86158xxxx1795
messaging_product String Yes whatsapp Channel for sending messages, must be "whatsapp" when sending WhatsApp messages
block_users User Object Yes List of user(s) to block.Each element contains a user field.

User

Parameter Name Type Required Example Description
user String Yes 861xxx The phone number or WhatsApp ID to be blocked.

Request Body example

{
    "appkey": "8eoKFyos",
    "messaging_product": "whatsapp",
    "business_phone": "xxx",
    "block_users": [
        {
            "user": "xxx"
        }
    ]
}

Response Parameters

Parameter Name Description
block_usersObject removed-users - List of removed successfully blocked users。
removed_usersObject List of removed successfully blocked users.Contains values of both: input

Response SUCCESS

{
    "code": 0,
    "data": {
        "block_users": {
            "removed_users": [
                {
                    "input": "xxx",
                    "wa_id": "xxx"
                }
            ]
        },
        "messaging_product": "whatsapp"
    },
    "message": "请求成功"
}

Get List of Blocked Numbers

Use this endpoint to get a list of blocked numbers on your WhatsApp Business number.

API

  • URL：https://api2.nxcloud.com/api/wa/getBlockUsers
  • Method：POST
  • Content-Type：application/json
  • Requires authentication: Yes

Request Body

Parameter Name Type Required Example Description
appkey String Yes Appkey of the NxCloud WhatsApp application
business_phone String Yes 86158xxxx1795 WhatsApp number , including country code. e.g., 86158xxxx1795
messaging_product String Yes whatsapp Channel for sending messages, must be "whatsapp" when sending WhatsApp messages
limit Long Yes/No Maximum number of blocked users to fetch in the request.
after String Yes/No
before String Yes/No

Request Body example

{
    "appkey": "xxx",
    "messaging_product": "whatsapp",
    "business_phone": "852xxx"
}

Response Parameters

Parameter Name Description
dataObject wa_id Unique ID of a WhatsApp user
pagingObject paging

Response SUCCESS

{
    "code": 0,
    "data": {
        "data": [
            {
                "messaging_product": "whatsapp",
                "wa_id": "xxx"
            },
            {
                "messaging_product": "whatsapp",
                "wa_id": "xxx"
            }
        ],
        "paging": {
            "cursors": {
                "before": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3NTM4NDc1MzgxOTk5NzAifQZDZD",
                "after": "eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3NTM4NDc1MzgxOTk5NzAifQZDZD"
            }
        }
    },
    "message": "请求成功"
}