CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-github-binarywang--weixin-java-mp

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

—

Pending
Overview
Eval results
Files

advanced-services.mddocs/

Advanced Services

Additional specialized services for extended WeChat Official Account functionality including QR codes, customer service, analytics, OAuth2, and other advanced features.

QR Code Management

interface WxMpQrcodeService {
  // Temporary QR codes
  WxMpQrCodeTicket qrCodeCreateTmp(int sceneId, Integer expireSeconds) throws WxErrorException;
  WxMpQrCodeTicket qrCodeCreateTmp(String sceneStr, Integer expireSeconds) throws WxErrorException;
  
  // Permanent QR codes
  WxMpQrCodeTicket qrCodeCreateLastTicket(int sceneId) throws WxErrorException;
  WxMpQrCodeTicket qrCodeCreateLastTicket(String sceneStr) throws WxErrorException;
  
  // QR code images
  File qrCodePicture(WxMpQrCodeTicket ticket) throws WxErrorException;
  String qrCodePictureUrl(String ticket) throws WxErrorException;
  String qrCodePictureUrl(String ticket, boolean needShortUrl) throws WxErrorException;
}

class WxMpQrCodeTicket implements Serializable {
  private String ticket;
  private Integer expireSeconds;
  private String url;
  
  public String getTicket();
  public void setTicket(String ticket);
  public Integer getExpireSeconds();
  public void setExpireSeconds(Integer expireSeconds);
  public String getUrl();
  public void setUrl(String url);
}

Customer Service (Kefu)

interface WxMpKefuService {
  // Send customer service messages
  boolean sendKfMessage(WxMpKefuMessage message) throws WxErrorException;
  boolean sendKfTyping(String openid) throws WxErrorException;
  boolean sendKfMessage(WxMpKefuMessage message, String kfAccount) throws WxErrorException;
  
  // Customer service account management
  WxMpKfList kfList() throws WxErrorException;
  WxMpKfOnlineList kfOnlineList() throws WxErrorException;
  boolean kfAccountAdd(WxMpKfAccount account) throws WxErrorException;
  boolean kfAccountUpdate(WxMpKfAccount account) throws WxErrorException;
  boolean kfAccountInviteWorker(WxMpKfAccount kfAccount) throws WxErrorException;
  boolean kfAccountUploadHeadImg(String media, String kfAccount) throws WxErrorException;
  boolean kfAccountDel(String kfAccount) throws WxErrorException;
  
  // Session management
  WxMpKfSessionList kfSessionList(String kfAccount) throws WxErrorException;
  WxMpKfSessionList kfSessionGetWaitCase() throws WxErrorException;
  boolean kfSessionCreate(String kfAccount, String openid) throws WxErrorException;
  boolean kfSessionClose(String kfAccount, String openid) throws WxErrorException;
  WxMpKfSession kfSessionGetSession(String openid) throws WxErrorException;
  
  // Message records
  WxMpKfMsgList kfMsgList(Date startTime, Date endTime, Long msgId, Integer number) throws WxErrorException;
}

class WxMpKefuMessage implements Serializable {
  private String toUser;
  private String msgType;
  private String content;
  private String mediaId;
  private String thumbMediaId;
  private String title;
  private String description;
  private String musicUrl;
  private String hqMusicUrl;
  private List<WxMpKefuMessage.WxArticle> articles;
  private String kfAccount;
  private WxMpKefuMessage.KfMaInfo maInfo;
  
  // Static factory methods
  public static WxMpKefuMessage TEXT();
  public static WxMpKefuMessage IMAGE();
  public static WxMpKefuMessage VOICE();
  public static WxMpKefuMessage VIDEO();
  public static WxMpKefuMessage MUSIC();
  public static WxMpKefuMessage NEWS();
  public static WxMpKefuMessage MPNEWS();
  public static WxMpKefuMessage WXCARD();
  public static WxMpKefuMessage MINIPROGRAMPAGE();
  
  public static class WxArticle implements Serializable {
    private String title;
    private String description;
    private String url;
    private String picUrl;
    
    // Getters and setters
  }
  
  public static class KfMaInfo implements Serializable {
    private String appid;
    private String pagepath;
    
    // Getters and setters
  }
}

Data Analytics

interface WxMpDataCubeService {
  // User analytics
  List<WxDataCubeUserSummary> getUserSummary(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeUserCumulate> getUserCumulate(Date beginDate, Date endDate) throws WxErrorException;
  
  // Article analytics
  List<WxDataCubeArticleSummary> getArticleSummary(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeArticleTotal> getArticleTotal(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeUserRead> getUserRead(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeUserReadHour> getUserReadHour(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeUserShare> getUserShare(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeUserShareHour> getUserShareHour(Date beginDate, Date endDate) throws WxErrorException;
  
  // Interface analytics
  List<WxDataCubeInterfaceSummary> getInterfaceSummary(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeInterfaceSummaryHour> getInterfaceSummaryHour(Date beginDate, Date endDate) throws WxErrorException;
  
  // Message analytics
  List<WxDataCubeMsgDistMonth> getUpstreamMsgDistMonth(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeMsgDistWeek> getUpstreamMsgDistWeek(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeMsgDist> getUpstreamMsgDist(Date beginDate, Date endDate) throws WxErrorException;
  List<WxDataCubeMsgDistHour> getUpstreamMsgDistHour(Date beginDate, Date endDate) throws WxErrorException;
}

OAuth2 Authentication

interface WxOAuth2Service {
  // Authorization URL building
  String buildAuthorizationUrl(String redirectUri, String scope, String state);
  
  // Access token operations
  WxOAuth2AccessToken getAccessToken(String code) throws WxErrorException;
  WxOAuth2AccessToken refreshAccessToken(String refreshToken) throws WxErrorException;
  boolean validateAccessToken(WxOAuth2AccessToken accessToken);
  
  // User information
  WxOAuth2UserInfo getUserInfo(WxOAuth2AccessToken accessToken, String lang) throws WxErrorException;
  
  // Check access token validity
  boolean checkAccessToken(String accessToken, String openid) throws WxErrorException;
}

class WxOAuth2AccessToken implements Serializable {
  private String accessToken;
  private Integer expiresIn;
  private String refreshToken;
  private String openId;
  private String scope;
  private String unionId;
  
  // Getters and setters
}

class WxOAuth2UserInfo implements Serializable {
  private String openId;
  private String nickname;
  private Integer sex;
  private String province;
  private String city;
  private String country;
  private String headImgUrl;
  private List<String> privilege;
  private String unionId;
  
  // Getters and setters
}

Mass Messaging

interface WxMpMassMessageService {
  // Group messaging
  WxMpMassSendResult massGroupMessageSend(WxMpMassGroupMessage message) throws WxErrorException;
  WxMpMassSendResult massOpenIdsMessageSend(WxMpMassOpenIdsMessage message) throws WxErrorException;
  WxMpMassSendResult massMessagePreview(WxMpMassPreviewMessage message) throws WxErrorException;
  
  // Media upload for mass messages
  WxMpMassUploadResult massVideoUpload(WxMpMassVideo video) throws WxErrorException;
  WxMpMassSendResult massNewsUpload(WxMpMassNews news) throws WxErrorException;
  
  // Mass message status
  WxMpMassSendResult massMessageGet(String msgId) throws WxErrorException;
  void massMessageDelete(String msgId, Integer articleIdx) throws WxErrorException;
}

class WxMpMassGroupMessage extends WxMpMassMessage {
  private WxMpMassTagMessage filter;
  
  public static class WxMpMassTagMessage {
    private Boolean isToAll;
    private String tagId;
    
    // Getters and setters
  }
}

class WxMpMassOpenIdsMessage extends WxMpMassMessage {
  private List<String> toUsers;
  
  // Getters and setters
}

Store Management

interface WxMpStoreService {
  // Store operations
  void storeAdd(WxMpStoreBaseInfo storeBaseInfo) throws WxErrorException;
  WxMpStoreBaseInfo storeGet(String poiId) throws WxErrorException;
  void storeDelete(String poiId) throws WxErrorException;
  void storeUpdate(WxMpStoreBaseInfo storeBaseInfo) throws WxErrorException;
  
  // Store list
  WxMpStoreListResult storeList(int begin, int limit) throws WxErrorException;
  
  // Category management
  List<WxMpStoreCategory> storeCategoryList() throws WxErrorException;
}

class WxMpStoreBaseInfo implements Serializable {
  private String sid;
  private String businessName;
  private String branchName;
  private String province;
  private String city;
  private String district;
  private String address;
  private String telephone;
  private List<String> categories;
  private Double offsetType;
  private Double longitude;
  private Double latitude;
  private List<WxMpStorePhoto> photoList;
  private String introduction;
  private String recommend;
  private String special;
  private String openTime;
  private Integer avgPrice;
  
  // Getters and setters
}

Card Management

interface WxMpCardService {
  // Card creation and management
  WxMpCardCreateResult createCard(WxMpCardCreateRequest request) throws WxErrorException;
  WxMpCard getCard(String cardId) throws WxErrorException;
  boolean updateCard(WxMpCardUpdateRequest request) throws WxErrorException;
  boolean deleteCard(String cardId) throws WxErrorException;
  
  // Card codes
  WxMpCardResult getCardDetail(String cardId, String code) throws WxErrorException;
  WxMpCardResult consumeCard(String code, String cardId) throws WxErrorException;
  WxMpCardResult decryptCardCode(String encryptCode) throws WxErrorException;
  
  // QR code for cards
  WxMpCardQrcodeCreateResult createQrcode(WxMpCardQrcodeCreateRequest request) throws WxErrorException;
  
  // Card colors and locations
  List<WxMpCardColor> getCardColors() throws WxErrorException;
  WxMpCardLocationResult getCardLocations(int offset, int count) throws WxErrorException;
  
  // Batch operations
  List<String> batchGetCardList(int offset, int count, String statusList) throws WxErrorException;
  WxMpCardResult updateCardStock(String cardId, Integer increase) throws WxErrorException;
}

Device Management (IoT)

interface WxMpDeviceService {
  // Device authorization  
  WxDeviceAuthorizeResult authorize(List<WxDevice> deviceList) throws WxErrorException;
  
  // Device operations
  WxDeviceSearchResult search(List<String> deviceIds) throws WxErrorException;
  boolean bind(String openid, String deviceId) throws WxErrorException;
  boolean unbind(String openid, String deviceId) throws WxErrorException;
  boolean compelBind(String openid, String deviceId) throws WxErrorException;
  boolean compelUnbind(String openid, String deviceId) throws WxErrorException;
  
  // Device status
  WxDeviceStatusResult getStatus(String deviceId) throws WxErrorException;
  
  // Message transmission
  boolean transmitMessage(WxDeviceMessage deviceMessage) throws WxErrorException;
}

class WxDevice implements Serializable {
  private String deviceId;
  private String deviceType;
  
  // Getters and setters
}

class WxDeviceMessage implements Serializable {
  private String deviceType;
  private String deviceId;
  private String openId;
  private String content;
  
  // Getters and setters
}

AI Services

interface WxMpAiOpenService {
  // Voice recognition
  WxMpAiOpenVoiceToTextResult voiceToText(String voiceFileMediaId, String format, Integer rate, String lang) throws WxErrorException;
  
  // Text translation
  WxMpAiOpenTranslateResult translate(String lfrom, String lto, String sourceContent) throws WxErrorException;
  
  // Image operations
  WxMpAiOpenResult qrCodeScan(String imgUrl) throws WxErrorException;
  WxMpAiOpenResult superResolution(String imgUrl) throws WxErrorException;
}

WiFi Services

interface WxMpWifiService {
  // WiFi device management
  WxMpWifiShopListResult listShop(int pageIndex, int pageSize) throws WxErrorException;
  WxMpWifiShopResult getShop(Integer shopId) throws WxErrorException;
  void updateShop(Integer shopId, String ssid, String password) throws WxErrorException;
  void clearShopPassword(Integer shopId) throws WxErrorException;
  
  // Device operations
  WxMpWifiDeviceResult addDevice(Integer shopId, String ssid, String password) throws WxErrorException;
  void deleteDevice(String mac) throws WxErrorException;
  WxMpWifiDeviceListResult listDevice(Integer shopId, Integer pageIndex, Integer pageSize) throws WxErrorException;
}

Subscribe Message Service

interface WxMpSubscribeMsgService {
  // Subscribe message operations  
  WxMpSubscribeMsgSendResult sendSubscribeMsg(WxMpSubscribeMsgSendRequest request) throws WxErrorException;
  List<WxMpSubscribeMessage> getSubscribeTemplateList() throws WxErrorException;
  String addSubscribeTemplate(String shortTemplateId, List<Integer> kidList, String sceneDesc) throws WxErrorException;
  boolean deleteSubscribeTemplate(String priTmplId) throws WxErrorException;
  List<WxMpSubscribeCategory> getSubscribeCategoryList() throws WxErrorException;
}

class WxMpSubscribeMsgSendRequest implements Serializable {
  private String touser;
  private String template_id;
  private String page;
  private String miniprogram_state;
  private String lang;
  private Map<String, TemplateData> data;
  
  public static class TemplateData {
    private String value;
  }
}

Usage Examples

QR Code Operations

// Create temporary QR code with scene ID
WxMpQrCodeTicket tempTicket = wxService.getQrcodeService()
    .qrCodeCreateTmp(12345, 600); // 10 minutes expiry

// Create permanent QR code with scene string
WxMpQrCodeTicket permTicket = wxService.getQrcodeService()
    .qrCodeCreateLastTicket("user_register");

// Download QR code image
File qrCodeFile = wxService.getQrcodeService().qrCodePicture(tempTicket);

// Get QR code URL
String qrCodeUrl = wxService.getQrcodeService()
    .qrCodePictureUrl(tempTicket.getTicket(), true);

Customer Service Messages

// Send text message
WxMpKefuMessage textMsg = WxMpKefuMessage.TEXT()
    .toUser("user_openid")
    .content("Hello, how can I help you?")
    .build();
wxService.getKefuService().sendKfMessage(textMsg);

// Send image message
WxMpKefuMessage imageMsg = WxMpKefuMessage.IMAGE()
    .toUser("user_openid")
    .mediaId("media_id")
    .build();
wxService.getKefuService().sendKfMessage(imageMsg);

// Send news message
WxMpKefuMessage newsMsg = WxMpKefuMessage.NEWS()
    .toUser("user_openid")
    .addArticle("Title", "Description", "https://example.com", "https://example.com/pic.jpg")
    .build();
wxService.getKefuService().sendKfMessage(newsMsg);

OAuth2 Authentication Flow

// Step 1: Build authorization URL
String authUrl = wxService.getOAuth2Service().buildAuthorizationUrl(
    "https://yoursite.com/callback", 
    "snsapi_userinfo", 
    "state123"
);

// Step 2: Handle callback and get access token
public void handleCallback(String code, String state) {
    try {
        WxOAuth2AccessToken accessToken = wxService.getOAuth2Service().getAccessToken(code);
        
        // Step 3: Get user information
        WxOAuth2UserInfo userInfo = wxService.getOAuth2Service()
            .getUserInfo(accessToken, "zh_CN");
        
        System.out.println("User: " + userInfo.getNickname());
        System.out.println("OpenID: " + userInfo.getOpenId());
        System.out.println("UnionID: " + userInfo.getUnionId());
        
    } catch (WxErrorException e) {
        System.err.println("OAuth2 error: " + e.getError().getErrorMsg());
    }
}

Analytics Data Retrieval

// Get user summary data
Calendar cal = Calendar.getInstance();
cal.add(Calendar.DAY_OF_MONTH, -7);
Date beginDate = cal.getTime();
Date endDate = new Date();

List<WxDataCubeUserSummary> userSummary = wxService.getDataCubeService()
    .getUserSummary(beginDate, endDate);

for (WxDataCubeUserSummary summary : userSummary) {
    System.out.println("Date: " + summary.getRefDate());
    System.out.println("New users: " + summary.getNewUser());
    System.out.println("Cancel users: " + summary.getCancelUser());
}

// Get article analytics
List<WxDataCubeArticleSummary> articleSummary = wxService.getDataCubeService()
    .getArticleSummary(beginDate, endDate);

for (WxDataCubeArticleSummary article : articleSummary) {
    System.out.println("Article reads: " + article.getIntPageReadUser());
    System.out.println("Article shares: " + article.getIntPageShareUser());
}

Mass Messaging

// Send to all users
WxMpMassGroupMessage groupMessage = WxMpMassGroupMessage.builder()
    .msgType(WxConsts.MassMsgType.MPNEWS)
    .mediaId("news_media_id")
    .sendIgnoreReprint(false)
    .build();

// Set filter for all users
WxMpMassGroupMessage.WxMpMassTagMessage filter = 
    new WxMpMassGroupMessage.WxMpMassTagMessage();
filter.setIsToAll(true);
groupMessage.setFilter(filter);

WxMpMassSendResult result = wxService.getMassMessageService()
    .massGroupMessageSend(groupMessage);

// Send to specific users
List<String> openIds = Arrays.asList("openid1", "openid2", "openid3");
WxMpMassOpenIdsMessage openIdsMessage = WxMpMassOpenIdsMessage.builder()
    .msgType(WxConsts.MassMsgType.TEXT)
    .content("Hello everyone!")
    .toUsers(openIds)
    .build();

wxService.getMassMessageService().massOpenIdsMessageSend(openIdsMessage);

Store Management

// Add new store
WxMpStoreBaseInfo store = new WxMpStoreBaseInfo();
store.setBusinessName("My Store");
store.setBranchName("Main Branch");
store.setProvince("Beijing");
store.setCity("Beijing");
store.setAddress("123 Main Street");
store.setTelephone("010-12345678");
store.setLatitude(39.9042);
store.setLongitude(116.4074);

wxService.getStoreService().storeAdd(store);

// Get store list
WxMpStoreListResult storeList = wxService.getStoreService().storeList(0, 20);
for (WxMpStoreBaseInfo storeInfo : storeList.getBusinessList()) {
    System.out.println("Store: " + storeInfo.getBusinessName());
}

Device Management

// Authorize devices
List<WxDevice> devices = Arrays.asList(
    new WxDevice("device_id_1", "device_type_1"),
    new WxDevice("device_id_2", "device_type_2")
);

WxDeviceAuthorizeResult authResult = wxService.getDeviceService().authorize(devices);

// Bind device to user
wxService.getDeviceService().bind("user_openid", "device_id_1");

// Send message to device
WxDeviceMessage deviceMsg = new WxDeviceMessage();
deviceMsg.setDeviceType("device_type_1");
deviceMsg.setDeviceId("device_id_1");
deviceMsg.setOpenId("user_openid");
deviceMsg.setContent("Hello device!");

wxService.getDeviceService().transmitMessage(deviceMsg);

Best Practices

  1. QR Codes: Use meaningful scene values for tracking and analytics
  2. Customer Service: Implement proper session management for better user experience
  3. OAuth2: Always validate tokens and handle refresh token scenarios
  4. Analytics: Regularly fetch and analyze data for business insights
  5. Mass Messages: Respect frequency limits and user preferences
  6. Error Handling: Implement comprehensive error handling for all services
  7. Rate Limiting: Monitor API usage to avoid hitting rate limits
  8. Data Privacy: Handle user data responsibly and comply with privacy regulations

Error Handling

public class AdvancedServiceErrorHandler {
    
    public static void handleQrCodeError(WxErrorException e) {
        switch (e.getError().getErrorCode()) {
            case 45001:
                System.err.println("QR code limit exceeded");
                break;
            case 45002:
                System.err.println("QR code refresh frequency exceeded");
                break;
            default:
                System.err.println("QR code error: " + e.getError().getErrorMsg());
        }
    }
    
    public static void handleOAuth2Error(WxErrorException e) {
        switch (e.getError().getErrorCode()) {
            case 40029:
                System.err.println("Invalid OAuth2 code");
                break;
            case 40030:
                System.err.println("Invalid refresh token");
                break;
            case 42001:
                System.err.println("Access token expired");
                break;
            default:
                System.err.println("OAuth2 error: " + e.getError().getErrorMsg());
        }
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-com-github-binarywang--weixin-java-mp

docs

advanced-services.md

index.md

material-management.md

menu-management.md

message-handling.md

service-management.md

shopping-guide.md

template-messaging.md

user-management.md

tile.json