An Official Account operator can log in to the Weixin Official Accounts Platform to blacklist followers. We also provide a set of blacklist management APIs to make the operations easier for developers.

1. Obtaining the Official Account's Blacklist

This API is used to obtain the Official Account's blacklist, which consists of a batch of OpenIDs (an OpenID is an encrypted Weixin ID that is unique to each user for each Official Account).

With this API, a maximum of 10,000 OpenIDs can be fetched at a time. If a large number of users are contained in the blacklist, you can fetch the blacklist multiple times.

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/members/getblacklist?access_token=ACCESS_TOKEN

JSON Data

{"begin_openid":"OPENID1"
}

If begin_openid is left empty, the list is fetched from the beginning by default.

Response

The JSON packet returned for a successful request

{
 "total":23000,
 "count":10000,
 "data":{"
    openid":[
       "OPENID1",
       "OPENID2",
       ...,
       "OPENID10000"
    ]
  },
  "next_openid":"OPENID10000"
}

The JSON packet returned for a failed request (in this case, the error is caused by an invalid AppID):

{"errcode":40013,"errmsg":"invalid appid"}

Error codes

Error Code Description
-1 System is busy.
40003 Invalid OpenID
49003 The OpenID entered does not belong to this AppID.

Note:

When the number of OpenIDs in the Official Account's blacklist exceeds 10,000, you can fetch the blacklist multiple times by entering the value of next_openid.

When the API is called, the next_openid value in the response for the previous request is used as the next_openid value in the current request.

2. Blacklisting Users

This API is used to blacklist a batch of users for an Official Account. The blacklist consists of a batch of OpenIDs (an OpenID is an encrypted Weixin ID that is unique to each user for each Official Account).

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/members/batchblacklist?access_token=ACCESS_TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for calling the API
openid_list Yes The OpenID of the user to be blacklisted. A maximum of 20 users can be blacklisted at a time.

JSON Data

{
 "openid_list":["OPENID1"," OPENID2"]
}

Response

The JSON data packet returned for a successful request

{
"errcode": 0,
"errmsg": "ok"
}

The JSON packet returned for a failed request (in this case, the error is caused by an invalid AppID):

{"errcode":40013,"errmsg":"invalid appid"}

Error codes

Error Code Description
-1 System is busy.
40003 Invalid OpenID
49003 The OpenID entered does not belong to this AppID.
40032 A maximum of 20 users can be blacklisted at a time.

3. Un-blacklisting Users

This API is used to un-blacklist a batch of users for an Official Account. The blacklist consists of a batch of OpenIDs (an OpenID is an encrypted Weixin ID that is unique to each user for each Official Account).

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/members/batchunblacklist?access_token=ACCESS_TOKEN

Parameters

Parameter Required Description
access_token Yes The credential for calling the API
openid_list Yes The OpenID of the user to be blacklisted. A maximum of 20 users can be blacklisted at a time.

JSON Data

{
 "openid_list":["OPENID1"," OPENID2"]
}

Response

The JSON data packet returned for a successful request

{
"errcode": 0,
"errmsg": "ok"
}

The JSON packet returned for a failed request (in this case, the error is caused by an invalid AppID):

{"errcode":40013,"errmsg":"invalid appid"}

Error codes

Error Code Description
-1 System is busy.
40003 Invalid OpenID
49003 The OpenID entered does not belong to this AppID.
40032 A maximum of 20 users can be blacklisted at a time.