Weixin public doc

With the user tag management-related APIs, you can create, query, modify and delete the Official Account tags, and tag and untag users.

Tag Management

1. Creating Tags

A maximum of 100 tags can be created for an Official Account.

API Request Format

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

POST data format: JSON POST data example:

{   "tag" : {     "name" : "Guangdong"//Tag Name  } }

Parameters

Parameter	Description
access_token	Credential for calling API
name	Tag name, with a maximum length of 30 characters (bytes).

Response (example of the JSON packet returned for a successful request)

{  "tag":{ "id":134,//Tag ID "name":"Guangdong" } }

Response Parameters

Parameter	Description
id	Tag ID assigned by Weixin
name	UTF8-encoded tag name

Error Codes

Error Code	Description
-1	System is busy.
45157	Invalid tag name. Duplicate names are not allowed.
45158	Tag name length exceeds 30 characters (bytes).
45056	Too many tags created. The number of tags cannot be greater than 100.

2. Obtaining the Official Account's Created Tags

API Request Format

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

Response

{   
"tags":[{       
    "id":1,       
    "name":"Coca Cola Stars",      
    "count":0 //Number of followers under this tag
},
{   
    "id":2,   
    "name":"Starred Group",   
    "count":0
},
{   
    "id":127,  
    "name":"Guangdong",  
    "count":5 
 }   
] }

3. Editing Tags

API Request Format

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

POST data format: JSON POST data example:

{   "tag" : {     "id" : 134,     "name" : "Cantonese"   } }

Response

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

Error Codes

Error Code	Description
-1	System is busy.
45157	Invalid tag name. Duplicate names are not allowed.
45158	Tag name length exceeds 30 characters (bytes).
45058	The reserved tags of the systems 0, 1 and 2 are non-editable.

4. Deleting Tags

Note: If the number of followers under a tag exceeds 100,000, the tag cannot be deleted directly. You need to untag followers in the tag's OpenID list to reduce the number of followers to 100,000 or less before you can delete the tag.

API Request Format

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

POST data format: JSON POST data example:

{   "tag":{        "id" : 134   } }

Response

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

Error Codes

Error Code	Description
-1	System is busy.
45058	The reserved tags of the systems 0, 1 and 2 are non-editable.
45057	This tag has more than 100, 000 followers and cannot be directly deleted.

5. Obtaining the Follower List Under a Tag

API Request Format

HTTP request method: GET (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/user/tag/get?access_token=ACCESS_TOKEN

POST data format: JSON POST data example:

{   "tagid" : 134,   "next_openid":""// The first OpenID to be fetched. If it is left empty, the list is fetched from the beginning. |

Response (Example of returned JSON packet for a successful request)

{  
    "count":2,//Number of fetched followers   
    "data":{//List of followers
    "openid":[  
    "ocYxcuAEy30bX0NXmGn4ypqx3tI0",    
    "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"  ]  
},  
    "next_openid":"ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"// The OpenID of the last user in the fetched list. 
}

Error Codes

Error Code	Description
-1	System is busy.
40003	Invalid OpenID
45159	Invalid tag_id

User Management

A maximum of 20 tags can be set for a user under an Official Account.

1. Tagging Users in Batch

API Request Format

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

POST data example:

{   
    "openid_list" : [//List of followers    
    "ocYxcuAEy30bX0NXmGn4ypqx3tI0",    
    "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"   ],   
    "tagid" : 134
 }

Response (Example of returned JSON packet for a successful request)

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

Error Codes

Error Code	Description
-1	System is busy.
40032	The number of OpenIDs in each list cannot exceed 50.
45159	Invalid tag
45059	A number of tags for a follower exceeds the limit. A maximum of 20 tags are allowed for a user.
40003	Invalid OpenID
49003	The OpenID entered does not belong to this AppID.

2. Untagging Users in Batch

API Request Format

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

POST data format: JSON POST data example:

{   
    "openid_list" : [//List of followers     
    "ocYxcuAEy30bX0NXmGn4ypqx3tI0",     
    "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"   ],   
    "tagid" : 134
 }

Response (Example of returned JSON packet for a successful request)

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

Error Codes

Error Code	Description
-1	System is busy.
40032	The number of OpenIDs in each list cannot exceed 50.
45159	Invalid tag
40003	Invalid OpenID
49003	The OpenID entered does not belong to this AppID.

3. Obtaining Tag List for a User

API Request Format

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

POST data format: JSON POST data example:

{   "openid" : "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y" }

Response (Example of returned JSON packet for a successful request):

{  "tagid_list":[//List of tags for the user 134, 2 ] }

Error Codes

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