0
# WeChat Official Account Java SDK (weixin-java-mp)
1

2
Comprehensive Java SDK for WeChat Official Account development providing complete API coverage for user management, messaging, materials, menus, and all WeChat platform features.
3

4
## Package Information
5

6
- **Package Name**: weixin-java-mp
7
- **Package Type**: Maven
8
- **Group ID**: com.github.binarywang
9
- **Artifact ID**: weixin-java-mp
10
- **Language**: Java
11
- **Installation**: Add to pom.xml:
12
  ```xml
13
  <dependency>
14
    <groupId>com.github.binarywang</groupId>
15
    <artifactId>weixin-java-mp</artifactId>
16
    <version>4.7.0</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java { .api }
23
import me.chanjar.weixin.mp.api.WxMpService;
24
import me.chanjar.weixin.mp.api.impl.WxMpServiceImpl;
25
import me.chanjar.weixin.mp.config.WxMpConfigStorage;
26
import me.chanjar.weixin.mp.config.impl.WxMpDefaultConfigImpl;
27
import me.chanjar.weixin.mp.bean.result.WxMpUser;
28
import me.chanjar.weixin.common.error.WxErrorException;
29
```
30

31
## Basic Usage
32

33
```java
34
import me.chanjar.weixin.mp.api.WxMpService;
35
import me.chanjar.weixin.mp.api.impl.WxMpServiceImpl;
36
import me.chanjar.weixin.mp.config.impl.WxMpDefaultConfigImpl;
37
import me.chanjar.weixin.mp.bean.result.WxMpUser;
38

39
// Initialize configuration
40
WxMpDefaultConfigImpl config = new WxMpDefaultConfigImpl();
41
config.setAppId("your-app-id");
42
config.setSecret("your-app-secret");
43

44
// Create service instance
45
WxMpService wxService = new WxMpServiceImpl();
46
wxService.setWxMpConfigStorage(config);
47

48
// Use specific services
49
String accessToken = wxService.getAccessToken();
50
WxMpUser user = wxService.getUserService().userInfo("openid", "zh_CN");
51
```
52

53
## Architecture
54

55
The WeChat Official Account Java SDK follows a modular service-oriented architecture:
56

57
### Core Components
58
- **WxMpService**: Main service interface providing access to all functionality
59
- **WxMpConfigStorage**: Configuration management for app credentials and tokens
60
- **Service Interfaces**: 30+ specialized service interfaces for different WeChat features
61
- **Message Framework**: Complete message handling, routing, and response building system
62
- **Bean Classes**: Comprehensive data models for all WeChat API requests and responses
63

64
### HTTP Client Support
65
The SDK supports multiple HTTP client implementations:
66
- Apache HttpClient (default)
67
- OkHttp
68
- Jodd HTTP
69

70
## Capabilities
71

72
### Service Management
73

74
Core service initialization and configuration management.
75

76
```java { .api }
77
interface WxMpService extends WxService {
78
  String getAccessToken() throws WxErrorException;
79
  String getAccessToken(boolean forceRefresh) throws WxErrorException;
80
  WxMpConfigStorage getWxMpConfigStorage();
81
  void setWxMpConfigStorage(WxMpConfigStorage wxConfigProvider);
82
  boolean switchover(String mpId);
83
  WxMpService switchoverTo(String mpId);
84
}
85
```
86

87
[Service Management](./service-management.md)
88

89
### User Management
90

91
Comprehensive user information management, tagging, and blacklist operations.
92

93
```java { .api }
94
interface WxMpUserService {
95
  WxMpUser userInfo(String openid, String lang) throws WxErrorException;
96
  List<WxMpUser> userInfoList(List<String> openids, String lang) throws WxErrorException;
97
  void userUpdateRemark(String openid, String remark) throws WxErrorException;
98
  WxMpUserList userList(String nextOpenid) throws WxErrorException;
99
}
100
```
101

102
[User Management](./user-management.md)
103

104
### Message Handling
105

106
Complete message processing framework including routing, handling, and response building.
107

108
```java { .api }
109
class WxMpMessageRouter {
110
  WxMpMessageRouter rule();
111
  WxMpMessageRouterRule async(boolean async);
112
  WxMpMessageRouterRule handler(WxMpMessageHandler handler);
113
  WxMpXmlOutMessage route(WxMpXmlMessage message);
114
}
115

116
interface WxMpMessageHandler {
117
  WxMpXmlOutMessage handle(WxMpXmlMessage wxMessage, Map<String, Object> context, 
118
                          WxMpService wxMpService, WxSessionManager sessionManager) 
119
                          throws WxErrorException;
120
}
121
```
122

123
[Message Handling](./message-handling.md)
124

125
### Material Management
126

127
Upload, download, and manage permanent and temporary media materials.
128

129
```java { .api }
130
interface WxMpMaterialService {
131
  WxMediaUploadResult materialFileUpload(String mediaType, String fileName, InputStream inputStream) throws WxErrorException;
132
  WxMpMaterialUploadResult materialNewsUpload(WxMpMaterialNews news) throws WxErrorException;
133
  InputStream materialImageOrVoiceDownload(String mediaId) throws WxErrorException;
134
  WxMpMaterialVideoInfoResult materialVideoInfo(String mediaId) throws WxErrorException;
135
}
136
```
137

138
[Material Management](./material-management.md)
139

140
### Menu Management
141

142
Create, update, and delete custom menus for WeChat Official Accounts.
143

144
```java { .api }
145
interface WxMpMenuService {
146
  String menuCreate(WxMenu menu) throws WxErrorException;
147
  void menuDelete() throws WxErrorException;
148
  WxMenu menuGet() throws WxErrorException;
149
  WxMpGetSelfMenuInfoResult getSelfMenuInfo() throws WxErrorException;
150
}
151
```
152

153
[Menu Management](./menu-management.md)
154

155
### Template Messaging
156

157
Send template messages to users with dynamic content.
158

159
```java { .api }
160
interface WxMpTemplateMsgService {
161
  WxMpTemplateMsgResult sendTemplateMsg(WxMpTemplateMessage templateMessage) throws WxErrorException;
162
  List<WxMpTemplate> getAllPrivateTemplate() throws WxErrorException;
163
  String addTemplate(String shortTemplateId) throws WxErrorException;
164
  boolean delPrivateTemplate(String templateId) throws WxErrorException;
165
}
166
```
167

168
[Template Messaging](./template-messaging.md)
169

170
### Shopping Guide Services
171

172
Comprehensive shopping guide functionality for managing shopping guides, buyers, materials, tags, and mass messaging campaigns.
173

174
```java { .api }
175
interface WxMpGuideService {
176
  WxMpGuideResult addGuide(WxMpGuideAccount account) throws WxErrorException;
177
  WxMpGuideResult getGuide(String account, String guideOpenid) throws WxErrorException;
178
  WxMpGuideResult updateGuide(WxMpGuideAccount account) throws WxErrorException;
179
  WxMpGuideListResult getGuideList(Integer page, Integer num) throws WxErrorException;
180
}
181

182
interface WxMpGuideBuyerService {
183
  WxMpGuideBuyerResult addGuideBuyer(WxMpGuideBuyer buyer) throws WxErrorException;
184
  WxMpGuideBuyerListResult getGuideBuyerList(String guideAccount, Integer page, Integer num) throws WxErrorException;
185
  WxMpGuideBuyerRelationResult getGuideBuyerRelation(String guideAccount, String openid) throws WxErrorException;
186
}
187

188
interface WxMpGuideTagService {
189
  WxMpGuideTagResult newGuideTagOption(WxMpGuideTagOption tagOption) throws WxErrorException;
190
  WxMpGuideTagResult addGuideBuyerTag(String guideAccount, String openid, List<String> tagValueList) throws WxErrorException;
191
}
192
```
193

194
[Shopping Guide Services](./shopping-guide.md)
195

196
### QR Code Management
197

198
Generate temporary and permanent QR codes for user engagement.
199

200
```java { .api }
201
interface WxMpQrcodeService {
202
  WxMpQrCodeTicket qrCodeCreateTmp(int sceneId, Integer expireSeconds) throws WxErrorException;
203
  WxMpQrCodeTicket qrCodeCreateTmp(String sceneStr, Integer expireSeconds) throws WxErrorException;
204
  WxMpQrCodeTicket qrCodeCreateLastTicket(int sceneId) throws WxErrorException;
205
  WxMpQrCodeTicket qrCodeCreateLastTicket(String sceneStr) throws WxErrorException;
206
  File qrCodePicture(WxMpQrCodeTicket ticket) throws WxErrorException;
207
  String qrCodePictureUrl(String ticket, boolean needShortUrl) throws WxErrorException;
208
}
209
```
210

211
### QR Code Management, Customer Service, Analytics, and Other Services
212

213
Additional specialized services for WeChat Official Account functionality including QR code generation, customer service operations, data analytics, OAuth2 authentication, mass messaging, card management, and more.
214

215
Key services include:
216

217
```java { .api }
218
interface WxMpQrcodeService {
219
  WxMpQrCodeTicket qrCodeCreateTmp(int sceneId, Integer expireSeconds) throws WxErrorException;
220
  WxMpQrCodeTicket qrCodeCreateLastTicket(int sceneId) throws WxErrorException;
221
  File qrCodePicture(WxMpQrCodeTicket ticket) throws WxErrorException;
222
}
223

224
interface WxMpKefuService {
225
  boolean sendKfMessage(WxMpKefuMessage message) throws WxErrorException;
226
  WxMpKfList kfList() throws WxErrorException;
227
  boolean kfAccountAdd(WxMpKfAccount account) throws WxErrorException;
228
}
229

230
interface WxMpDataCubeService {
231
  List<WxDataCubeUserSummary> getUserSummary(Date beginDate, Date endDate) throws WxErrorException;
232
  List<WxDataCubeArticleSummary> getArticleSummary(Date beginDate, Date endDate) throws WxErrorException;
233
}
234

235
interface WxOAuth2Service {
236
  String buildAuthorizationUrl(String redirectUri, String scope, String state);
237
  WxOAuth2AccessToken getAccessToken(String code) throws WxErrorException;
238
  WxOAuth2UserInfo getUserInfo(WxOAuth2AccessToken token, String lang) throws WxErrorException;
239
}
240

241
interface WxMpMassMessageService {
242
  WxMpMassSendResult massGroupMessageSend(WxMpMassGroupMessage message) throws WxErrorException;
243
  WxMpMassSendResult massOpenIdsMessageSend(WxMpMassOpenIdsMessage message) throws WxErrorException;
244
}
245
```
246

247
### Advanced Services
248

249
Additional specialized services for extended WeChat functionality including analytics, OAuth2, mass messaging, and specialized integrations.
250

251
Key services include:
252

253
- **Analytics & Data**: Data cube services for user and content analytics  
254
- **OAuth2 Authentication**: Web-based user authorization and profile access
255
- **Mass Messaging**: Bulk message sending to user groups or segments
256
- **Store Management**: Location-based services and POI management
257
- **Device Management**: IoT device integration and communication
258
- **AI Services**: Voice recognition, translation, and image processing
259
- **Invoice Services**: Electronic invoice management and reimbursement
260
- **Card Management**: Membership cards, coupons, and loyalty programs
261
- **WiFi Services**: WiFi portal management and user engagement
262

263
[Advanced Services](./advanced-services.md)
264

265
## Configuration Types
266

267
```java { .api }
268
interface WxMpConfigStorage {
269
  String getAccessToken();
270
  boolean isAccessTokenExpired();
271
  void expireAccessToken();
272
  void updateAccessToken(WxAccessToken accessToken);
273
  String getAppId();
274
  String getSecret();
275
  String getToken();
276
  String getAesKey();
277
  long getExpiresTime();
278
  String getOAuth2redirectUri();
279
  String getHttpProxyHost();
280
  int getHttpProxyPort();
281
  String getHttpProxyUsername();
282
  String getHttpProxyPassword();
283
}
284

285
class WxMpHostConfig {
286
  public static String buildUrl(WxMpHostConfig hostConfig, String prefix, String path);
287
  // Host configuration for different deployment environments
288
}
289
```
290

291
## Exception Handling
292

293
```java { .api }
294
class WxErrorException extends Exception {
295
  private WxError error;
296
  public WxError getError();
297
  public String getMessage();
298
}
299

300
class WxError implements Serializable {
301
  private int errorCode;
302
  private String errorMsg;
303
  private String json;
304
  // Error details and codes
305
}
306
```
307

308
## Message Types
309

310
```java { .api }
311
class WxMpXmlMessage implements Serializable {
312
  private String toUser;
313
  private String fromUser;
314
  private Long createTime;
315
  private String msgType;
316
  private String content;
317
  private Long msgId;
318
  private String picUrl;
319
  private String mediaId;
320
  // Additional message fields based on type
321
}
322

323
abstract class WxMpXmlOutMessage {
324
  protected String toUserName;
325
  protected String fromUserName;
326
  protected Long createTime;
327
  protected String msgType;
328
  // Base class for all outgoing messages
329
}
330
```
331

332
## Constants
333

334
```java { .api }
335
class WxMpEventConstants {
336
  // Card Events
337
  public static final String CardPass = "card_pass_check";
338
  public static final String CardNotPass = "card_not_pass_check";
339
  public static final String UserGetCard = "user_get_card";
340
  public static final String UserGiftingCard = "user_gifting_card";
341
  public static final String UserDelCard = "user_del_card";
342
  public static final String UserConsumeCard = "user_consume_card";
343
  public static final String UserPayFromPayCell = "user_pay_from_pay_cell";
344
  public static final String UserViewCard = "user_view_card";
345
  public static final String UserEnterSessionFromCard = "user_enter_session_from_card";
346
  public static final String UpdateMemberCard = "update_member_card";
347
  public static final String CardSkuRemind = "card_sku_remind";
348
  public static final String CardPayOrder = "card_pay_order";
349
  public static final String SubmitMembercardUserInfo = "submit_membercard_user_info";
350

351
  // Store Events  
352
  public static final String PoiCheckNotify = "poi_check_notify";
353

354
  // Shake Events
355
  public static final String ShakeAroundUserShake = "ShakeAround_user_shake";
356
  public static final String ShakeAroundLotteryBind = "ShakeAround_lottery_bind";
357
}
358

359
enum WxMpApiUrl {
360
  // Comprehensive API endpoint definitions organized by category
361
  // Device, OAuth2, Menu, Material, User, Card, etc.
362
}
363
```