0
# User Management
1

2
Comprehensive user information management, tagging, and blacklist operations for WeChat Official Account users.
3

4
## User Information Service
5

6
```java { .api }
7
interface WxMpUserService {
8
  // Basic user information
9
  WxMpUser userInfo(String openid) throws WxErrorException;
10
  WxMpUser userInfo(String openid, String lang) throws WxErrorException;
11
  List<WxMpUser> userInfoList(List<String> openids) throws WxErrorException;
12
  List<WxMpUser> userInfoList(List<String> openids, String lang) throws WxErrorException;
13
  
14
  // User list management
15
  WxMpUserList userList(String nextOpenid) throws WxErrorException;
16
  
17
  // User remark management
18
  void userUpdateRemark(String openid, String remark) throws WxErrorException;
19
  
20
  // OpenID migration for account changes
21
  WxMpChangeOpenidResult changeOpenid(String fromAppid, List<String> openidList) throws WxErrorException;
22
}
23
```
24

25
## User Tag Service
26

27
```java { .api }
28
interface WxMpUserTagService {
29
  // Tag management
30
  WxUserTag tagCreate(String name) throws WxErrorException;
31
  List<WxUserTag> tagGet() throws WxErrorException;
32
  Boolean tagUpdate(Long id, String name) throws WxErrorException;
33
  Boolean tagDelete(Long id) throws WxErrorException;
34
  
35
  // User-tag relationships
36
  WxTagListUser tagListUser(Long tagid, String nextOpenid) throws WxErrorException;
37
  Boolean batchTagging(Long tagid, String[] openidList) throws WxErrorException;
38
  Boolean batchUntagging(Long tagid, String[] openidList) throws WxErrorException;
39
  List<Long> userTagList(String openid) throws WxErrorException;
40
}
41
```
42

43
## User Blacklist Service
44

45
```java { .api }
46
interface WxMpUserBlacklistService {
47
  // Blacklist management
48
  WxMpUserBlacklistGetResult getBlacklist(String nextOpenid) throws WxErrorException;
49
  void pushToBlacklist(List<String> openidList) throws WxErrorException;
50
  void pullFromBlacklist(List<String> openidList) throws WxErrorException;
51
}
52
```
53

54
## Data Models
55

56
### User Information
57

58
```java { .api }
59
class WxMpUser implements Serializable {
60
  private Boolean subscribe;
61
  private String openId;
62
  @Deprecated // WeChat stopped returning user profile info as of 2021-12-27
63
  private String nickname;
64
  private Integer sex;
65
  private String language;
66
  private String city;
67
  private String province;
68
  private String country;
69
  @Deprecated // WeChat stopped returning user profile info as of 2021-12-27
70
  private String headImgUrl;
71
  private Long subscribeTime;
72
  private String unionId;
73
  private String remark;
74
  private Long groupId;
75
  private Long[] tagIdList;
76
  private String subscribeScene;
77
  private Long qrScene;
78
  private String qrSceneStr;
79
  
80
  // Getters and setters
81
  public Boolean getSubscribe();
82
  public void setSubscribe(Boolean subscribe);
83
  public String getOpenId();
84
  public void setOpenId(String openId);
85
  @Deprecated // WeChat stopped returning user profile info as of 2021-12-27
86
  public String getNickname();
87
  @Deprecated // WeChat stopped returning user profile info as of 2021-12-27
88
  public void setNickname(String nickname);
89
  public Integer getSex();
90
  public void setSex(Integer sex);
91
  public String getLanguage();
92
  public void setLanguage(String language);
93
  public String getCity();
94
  public void setCity(String city);
95
  public String getProvince();
96
  public void setProvince(String province);
97
  public String getCountry();
98
  public void setCountry(String country);
99
  @Deprecated // WeChat stopped returning user profile info as of 2021-12-27
100
  public String getHeadImgUrl();
101
  @Deprecated // WeChat stopped returning user profile info as of 2021-12-27
102
  public void setHeadImgUrl(String headImgUrl);
103
  public Long getSubscribeTime();
104
  public void setSubscribeTime(Long subscribeTime);
105
  public String getUnionId();
106
  public void setUnionId(String unionId);
107
  public String getRemark();
108
  public void setRemark(String remark);
109
  public Long getGroupId();
110
  public void setGroupId(Long groupId);
111
  public Long[] getTagIdList();
112
  public void setTagIdList(Long[] tagIdList);
113
  public String getSubscribeScene();
114
  public void setSubscribeScene(String subscribeScene);
115
  public Long getQrScene();
116
  public void setQrScene(Long qrScene);
117
  public String getQrSceneStr();
118
  public void setQrSceneStr(String qrSceneStr);
119
}
120
```
121

122
### User List
123

124
```java { .api }
125
class WxMpUserList implements Serializable {
126
  private Long total;
127
  private Integer count;
128
  private WxMpOpenIdList data;
129
  private String nextOpenid;
130
  
131
  public Long getTotal();
132
  public void setTotal(Long total);
133
  public Integer getCount();
134
  public void setCount(Integer count);
135
  public WxMpOpenIdList getData();
136
  public void setData(WxMpOpenIdList data);
137
  public String getNextOpenid();
138
  public void setNextOpenid(String nextOpenid);
139
}
140

141
class WxMpOpenIdList implements Serializable {
142
  private List<String> openid;
143
  
144
  public List<String> getOpenid();
145
  public void setOpenid(List<String> openid);
146
}
147
```
148

149
### User Tags
150

151
```java { .api }
152
class WxUserTag implements Serializable {
153
  private Long id;
154
  private String name;
155
  private Integer count;
156
  
157
  public Long getId();
158
  public void setId(Long id);
159
  public String getName();
160
  public void setName(String name);
161
  public Integer getCount();
162
  public void setCount(Integer count);
163
}
164

165
class WxTagListUser implements Serializable {
166
  private Integer count;
167
  private WxMpOpenIdList data;
168
  private String nextOpenid;
169
  
170
  public Integer getCount();
171
  public void setCount(Integer count);
172
  public WxMpOpenIdList getData();
173
  public void setData(WxMpOpenIdList data);
174
  public String getNextOpenid();
175
  public void setNextOpenid(String nextOpenid);
176
}
177
```
178

179
### Blacklist Results
180

181
```java { .api }
182
class WxMpUserBlacklistGetResult implements Serializable {
183
  private Integer total;
184
  private Integer count;
185
  private WxMpOpenIdList data;
186
  private String nextOpenid;
187
  
188
  public Integer getTotal();
189
  public void setTotal(Integer total);
190
  public Integer getCount();
191
  public void setCount(Integer count);
192
  public WxMpOpenIdList getData();
193
  public void setData(WxMpOpenIdList data);
194
  public String getNextOpenid();
195
  public void setNextOpenid(String nextOpenid);
196
}
197
```
198

199
## User Query Support
200

201
```java { .api }
202
class WxMpUserQuery implements Serializable {
203
  private String nextOpenid;
204
  private String lang;
205
  
206
  public WxMpUserQuery();
207
  public WxMpUserQuery(String nextOpenid);
208
  public WxMpUserQuery(String nextOpenid, String lang);
209
  
210
  public String getNextOpenid();
211
  public void setNextOpenid(String nextOpenid);
212
  public String getLang();
213
  public void setLang(String lang);
214
}
215
```
216

217
## OpenID Change Result
218

219
```java { .api }
220
class WxMpChangeOpenidResult implements Serializable {
221
  private List<WxMpChangeOpenidItem> resultList;
222
  
223
  public List<WxMpChangeOpenidItem> getResultList();
224
  public void setResultList(List<WxMpChangeOpenidItem> resultList);
225
  
226
  public static class WxMpChangeOpenidItem implements Serializable {
227
    private String oriOpenid;
228
    private String newOpenid;
229
    private Integer errcode;
230
    private String errmsg;
231
    
232
    public String getOriOpenid();
233
    public void setOriOpenid(String oriOpenid);
234
    public String getNewOpenid();
235
    public void setNewOpenid(String newOpenid);
236
    public Integer getErrcode();
237
    public void setErrcode(Integer errcode);
238
    public String getErrmsg();
239
    public void setErrmsg(String errmsg);
240
  }
241
}
242
```
243

244
## Usage Examples
245

246
### Get User Information
247

248
```java
249
// Get single user info
250
WxMpUser user = wxService.getUserService().userInfo("openid123", "zh_CN");
251
System.out.println("User nickname: " + user.getNickname());
252
System.out.println("Subscribe time: " + user.getSubscribeTime());
253

254
// Get multiple users info
255
List<String> openids = Arrays.asList("openid1", "openid2", "openid3");
256
List<WxMpUser> users = wxService.getUserService().userInfoList(openids, "zh_CN");
257
for (WxMpUser u : users) {
258
    System.out.println("User: " + u.getOpenId() + " - " + u.getNickname());
259
}
260
```
261

262
### User List Pagination
263

264
```java
265
// Get first page of users
266
WxMpUserList userList = wxService.getUserService().userList(null);
267
System.out.println("Total users: " + userList.getTotal());
268

269
// Get next page if available
270
String nextOpenid = userList.getNextOpenid();
271
if (nextOpenid != null && !nextOpenid.isEmpty()) {
272
    WxMpUserList nextPage = wxService.getUserService().userList(nextOpenid);
273
    // Process next page
274
}
275

276
// Get all users with pagination
277
List<String> allOpenids = new ArrayList<>();
278
String currentOpenid = null;
279
do {
280
    WxMpUserList page = wxService.getUserService().userList(currentOpenid);
281
    if (page.getData() != null && page.getData().getOpenid() != null) {
282
        allOpenids.addAll(page.getData().getOpenid());
283
    }
284
    currentOpenid = page.getNextOpenid();
285
} while (currentOpenid != null && !currentOpenid.isEmpty());
286
```
287

288
### Update User Remarks
289

290
```java
291
// Update user remark
292
wxService.getUserService().userUpdateRemark("openid123", "VIP Customer");
293
```
294

295
### Tag Management
296

297
```java
298
// Create a new tag
299
WxUserTag newTag = wxService.getUserTagService().tagCreate("VIP Users");
300
Long tagId = newTag.getId();
301

302
// Get all tags
303
List<WxUserTag> tags = wxService.getUserTagService().tagGet();
304
for (WxUserTag tag : tags) {
305
    System.out.println("Tag: " + tag.getName() + " (ID: " + tag.getId() + ")");
306
}
307

308
// Update tag name
309
wxService.getUserTagService().tagUpdate(tagId, "Premium VIP Users");
310

311
// Delete tag
312
wxService.getUserTagService().tagDelete(tagId);
313
```
314

315
### User-Tag Operations
316

317
```java
318
// Tag users
319
String[] openids = {"openid1", "openid2", "openid3"};
320
wxService.getUserTagService().batchTagging(tagId, openids);
321

322
// Untag users
323
wxService.getUserTagService().batchUntagging(tagId, openids);
324

325
// Get users with specific tag
326
WxTagListUser taggedUsers = wxService.getUserTagService().tagListUser(tagId, null);
327
System.out.println("Users with tag: " + taggedUsers.getCount());
328

329
// Get tags for a specific user
330
List<Long> userTags = wxService.getUserTagService().userTagList("openid123");
331
System.out.println("User has " + userTags.size() + " tags");
332
```
333

334
### Blacklist Management
335

336
```java
337
// Get blacklist
338
WxMpUserBlacklistGetResult blacklist = wxService.getBlackListService().getBlacklist(null);
339
System.out.println("Blacklisted users: " + blacklist.getTotal());
340

341
// Add users to blacklist
342
List<String> usersToBlock = Arrays.asList("openid1", "openid2");
343
wxService.getBlackListService().pushToBlacklist(usersToBlock);
344

345
// Remove users from blacklist
346
List<String> usersToUnblock = Arrays.asList("openid1");
347
wxService.getBlackListService().pullFromBlacklist(usersToUnblock);
348

349
// Get all blacklisted users with pagination
350
List<String> allBlacklisted = new ArrayList<>();
351
String nextOpenid = null;
352
do {
353
    WxMpUserBlacklistGetResult page = wxService.getBlackListService().getBlacklist(nextOpenid);
354
    if (page.getData() != null && page.getData().getOpenid() != null) {
355
        allBlacklisted.addAll(page.getData().getOpenid());
356
    }
357
    nextOpenid = page.getNextOpenid();
358
} while (nextOpenid != null && !nextOpenid.isEmpty());
359
```
360

361
### Batch User Processing
362

363
```java
364
// Process all users in batches
365
String nextOpenid = null;
366
do {
367
    WxMpUserList userList = wxService.getUserService().userList(nextOpenid);
368
    
369
    if (userList.getData() != null && userList.getData().getOpenid() != null) {
370
        List<String> openids = userList.getData().getOpenid();
371
        
372
        // Process in smaller batches for user info
373
        for (int i = 0; i < openids.size(); i += 100) {
374
            int endIndex = Math.min(i + 100, openids.size());
375
            List<String> batch = openids.subList(i, endIndex);
376
            
377
            List<WxMpUser> users = wxService.getUserService().userInfoList(batch, "zh_CN");
378
            
379
            // Process user information
380
            for (WxMpUser user : users) {
381
                if (user.getSubscribe()) {
382
                    // Process subscribed users
383
                    System.out.println("Active user: " + user.getNickname());
384
                }
385
            }
386
        }
387
    }
388
    
389
    nextOpenid = userList.getNextOpenid();
390
} while (nextOpenid != null && !nextOpenid.isEmpty());
391
```
392

393
## Language Support
394

395
The user info APIs support language parameters:
396

397
- `zh_CN`: Simplified Chinese (default)
398
- `zh_TW`: Traditional Chinese
399
- `en`: English
400

401
```java
402
// Get user info in English
403
WxMpUser user = wxService.getUserService().userInfo("openid123", "en");
404
```
405

406
## User Sex Constants
407

408
User sex field values:
409
- `0`: Unknown
410
- `1`: Male  
411
- `2`: Female
412

413
## Subscribe Scene Values
414

415
Common subscribe scene values:
416
- `ADD_SCENE_SEARCH`: Search
417
- `ADD_SCENE_ACCOUNT_MIGRATION`: Account migration
418
- `ADD_SCENE_PROFILE_CARD`: Profile card
419
- `ADD_SCENE_QR_CODE`: QR code
420
- `ADD_SCENE_PROFILE_LINK`: Profile link
421
- `ADD_SCENE_PROFILE_ITEM`: Profile item
422
- `ADD_SCENE_PAID`: Paid
423
- `ADD_SCENE_WECHAT_ADVERTISEMENT`: WeChat advertisement
424
- `ADD_SCENE_OTHERS`: Others
425

426
## Error Handling
427

428
Common error scenarios:
429
- Invalid openid: Error code 40003
430
- User not subscribed: Subscribe field will be false
431
- Rate limiting: Error code 45009
432
- Invalid tag operations: Various error codes for tag-related failures
433

434
```java
435
try {
436
    WxMpUser user = wxService.getUserService().userInfo("invalid-openid");
437
} catch (WxErrorException e) {
438
    if (e.getError().getErrorCode() == 40003) {
439
        System.out.println("Invalid openid");
440
    }
441
}
442
```