itchat4j -- 用Java扩展个人微信号的能力

项目地址：itchat4j，该项目长期维护更新，欢迎star、fork、 pull requests、 issue。

示例项目程序点击此处下载。

来源

itchat是一个非常优秀的开源微信个人号接口，使用Python语言开发，提供了简单易用的API，可以很方便地对个人微信号进行扩展，实现自动回复，微信挂机机器人等，一直在关注这个项目，基于itchat开发过一个小项目，用来控制我的树莓派来播放音乐，效果还不错。

一直想实现一个java版本的itchat，由于工作太忙导致一拖再拖，这段时间稍微空闲了一些，仔细阅读了itchat的源码，终于完成了一个基础版本，由于主要灵感来源于itchat项目，所以这个项目的就暂时定名为itchat4j吧。

项目介绍

itchat是一个开源的微信个人号接口，使用Python调用微信从未如此简单。使用短短的几十行代码，你就可以完成一个能够处理所有信息的微信机器人。当然，itchat的使用远不止一个机器人，更多的功能等着你来发现，如今微信已经成为了个人社交的很大一部分，希望这个项目能够帮助你扩展你的个人的微信号、方便自己的生活。(引自itchat项目)

你可以轻松将itchat4j其集成在你个人的Java应用中，无论是SpringMVC、桌面程序还是嵌入式程序，只要使用的JDK是1.7以上的版本，都可以轻松接入。玩法很多，请打开你的脑洞，比如这些：

• Just for fun，把个人微信号扩展为"公众号"，在朋友面前装个X吧。
• 集成在你的个人应用（SpringMVC、Servlet、GUI）中，为应用提供更强的服务能力。
• 部署在你的服务器上，将监控信息、日志发送到你的微信号。
• 微信机器人，专业陪聊工具
• 控制树莓派、智能家居、智能硬件等具有开放接口的设备
• Anything you want ...

更新日志

• 2017-7-21：1.消息体封装为POJO类，更易操作。 2.增加处理文件消息接口。

• 2017-6-28：增加被动添加好友功能。

• 2017-6-23：增加获取群好友昵称功能，修复已知问题。

• 2017-6-16：增加微信状态维护。

• 2017-6-13：修复获取群列表为空问题，增加根据群ID获取群成员列表方法。

  ​

API说明

项目在不断更新中，API会有变动，请以具体代码为准

目前在package cn.zhouyafeng.itchat4j.api包中有两个静态类，即MessageTools和WechatTools，目前对外暴露的方法有：

1.获取好友昵称列表 WechatTools.getContactNickNameList()

此方法会返回好友昵称列表，其函数声明为：

public static List<String> getContactNickNameList()

2.获取好友完整信息列表 WechatTools.getContactList()

此方法会返回好友的完整信息，如昵称、备注、地区、头像链接等，其函数声明为：

public static List<JSONObject> getContactList()

3.获取群列表 WechatTools.getGroupIdList()

群列表与好友列表不同，在登陆后群列表其实是空的，只有主动发送消息或者收到一条群消息时，才能获取到这个群的信息，群列表会记录这个群的id，其格式为@@d052d34b9c9228830363013ee53deb461404f80ea353dbdd8fc9391cbf5f1c46。调用此方法会返回已知的群列表。其声明函数为：

public static List<String> getGroupIdList()

4.根据群ID获取群成员WechatTools.getMemberListByGroupId()

此方法根据群ID（格式为@@d052d34b9c9228830363013ee53deb461404f80ea353dbdd8fc9391cbf5f1c46）获取群成员列表。其函数声明为：

public static JSONArray getMemberListByGroupId(String groupId)

5.退出微信 WechatTools.logout()

退出itchat4j，不再处理消息，其函数声明为:

public static void logout()

6.获取微信在线状态WechatTools.getWechatStatus()

查询微信在线状态，在线返回true，离线返回false，其函数声明为

public static boolean getWechatStatus()

7.获取群昵称列表WechatTools.getGroupNickNameList()

获取群昵称列表,函数声明为：

public static List<String> getGroupNickNameList()

8.根据用户昵称修改用户备注MessageTools.remarkNameByNickName(String nickName, String remName)

根据用户昵称修改用户备注名称，其函数声明为：

public static void remarkNameByNickName(String nickName, String remName)

9. 根据好友昵称发送文本消息，MessageTools.sendMsgByNickName(String text, String nickName)

此方法根据用户昵称发送文本消息，注意，用户需在你的好友列表里，否则发送失败，如果你的好友列表里有存在昵称一样的多个用户，则只会给第一个匹配的好友发送消息。方法接受两个参数，text为要发送的文本消息，nickName为要发送消息的好友昵称，成功发送时返回true，失败返回false。其函数声明为：

public static boolean sendMsgByNickName(String text, String nickName)

10.根据ID发送文本消息， MessageTools.sendMsgById(String text, String id)

根据ID发送文本消息，发送者ID可以从msg里通过msg.getString("FromUserName")获取，格式为@@d052d34b9c9228830363013ee53deb461404f80ea353dbdd8fc9391cbf5f1c46（群消息）或@a257b99314d8313862cd44ab02fe0f81（非群消息），调用此方法可向指定id发送消息。其函数声明为：

public static void sendMsgById(String text, String id)

11.根据好友昵称发送图片消息，MessageTools.sendPicMsgByNickName(String nickName, String filePath)

此方法根据好友昵称发送图片消息，filePath为图片文件路径，如D:/itchat4j/pic/test.jpg，成功返回true，失败返回false。其函数声明为：

public static boolean sendPicMsgByNickName(String nickName, String filePath)

12.根据ID发送图片消息，MessageTools.sendPicMsgByUserId(String userId, String filePath)

此方法根据好友ID发送图片消息，filePath为图片文件路径，如D:/itchat4j/pic/test.jpg`，成功返回true，失败返回false。其函数声明为：

public static boolean sendPicMsgByUserId(String userId, String filePath)

13.根据好友昵称发送文件消息，MessageTools.sendFileMsgByNickName(String nickName, String filePath)

此方法根据好友昵称发送文件消息，文件可以为多种类型，如txt、PDF、小视频、语音、excel、docx等，发送时请保证文件后缀名正确。成功返回true，失败返回false。其函数声明为：

public static boolean sendPicFileByNickName(String nickName, String filePath)

14.根据ID发送文件消息，MessageTools.sendFileMsgByNickName(String nickName, String filePath)

此方法根据好友昵称发送文件消息，成功返回true，失败返回false。其函数声明为：

public static boolean sendFileMsgByUserId(String userId, String filePath)

15.处理好友添加请求，MessageTools.addFriend(BaseMsg msg, boolean accept)

当收到好友添加请求时，可调用此函数进行处理，msg为收到的好友添加请求消息，accept传true为接受好友请求，false为拒绝，其函数声明为：

public static void addFriend(BaseMsg msg, boolean accept)

TODO List 即将支持/正在开发

• 拉人进群功能

如何使用

项目在不断更新中，导入后的项目结构会有变动

itchat4j是一个Maven项目，下载源码后，可以以Maven项目的形式导入，导入后的项目结构如下图:

src/main/java是itchat4j的项目源码，在src/test/java目录下有两个小Demo：一个是基本功能的小示例，当前，itchat4j可以处理四类基本信息，文本、语音、图片和小视频，该示例在收到文本信息后自动回复，回复内容为收到的文本，当收到图片、语音、小视频时可以保存到指定的目录；一个是微信接入图灵机器人的小例子，如下图。

微信机器人使用截图

消息格式

对于收到的消息，itchat4j将其以POJO类的形式进行了封装，即在package cn.zhouyafeng.itchat4j.beans包中的BaseMsg类，其声明如下：

/**
 * 收到的微信消息
 * 
 * @author https://github.com/yaphone
 * @date 创建时间：2017年7月3日 下午10:28:06
 * @version 1.0
 *
 */
public class BaseMsg implements Serializable {
	/**
	 * 
	 */
	private static final long serialVersionUID = 1L;
	private int subMsgType;
	private int voiceLength;
	private String fileName;
	private int imgHeight;
	private String toUserName;
	private int hasProductId;
	private int imgStatus;
	private String url;
	private int imgWidth;
	private int forwardFlag;
	private int status;
	private String Ticket;
	/** 推荐消息报文 **/
	private RecommendInfo recommendInfo;
	private long createTime;
	private String newMsgId;
	/** 文本消息内容 **/
	private String text;
	/** 消息类型 **/
	private int msgType;
	/** 是否为群消息 **/
	private boolean groupMsg;
	private String msgId;
	private int statusNotifyCode;
	private AppInfo appInfo;
	private int appMsgType;
	private String Type;
	private int playLength;
	private String mediaId;
	private String content;
	private String statusNotifyUserName;
	/** 消息发送者ID **/
	private String fromUserName;
	private String oriContent;
	private String fileSize;

  //省略getter/setter方法

}

如何使用

如果你想引入自己的项目，请切换到pom.xml目录，执行mvn package命令，将生成的itchat4j的jar包引入即可。

简单入门教程

项目不断更新中，教程仅供参考

接下来，通过两个小Demo来演示一下如何使用itchat4j来扩展你的个人微信号，入门教程的项目源码可以从此处下载。以下几个demo在项目的src/test/java路径下可以找到，项目不断更新，请以实际代码为准。

Demo1: SimpleDemo

这个小Demo将会将收到的文本消息发送给发件人，如果是图片、语音或者小视频消息，将会保存在我们指定的路径下。

首先需要新建一个类来实现IMsgHandlerFace这个接口，这个类要做的就是我们需要完成的逻辑，该接口有若干个需要自己实现的方法，如textMsgHandle用于处理文本信息，picMsgHandle用于处理图片信息，viedoMsgHandle用于处理小视频信息，voiceMsgHandle用于处理语音信息等，代码如下：

package cn.zhouyafeng.itchat4j.face;

import cn.zhouyafeng.itchat4j.beans.BaseMsg;

/**
 * 消息处理接口
 * 
 * @author https://github.com/yaphone
 * @date 创建时间：2017年4月20日 上午12:13:49
 * @version 1.0
 *
 */
public interface IMsgHandlerFace {
	/**
	 * 
	 * @author https://github.com/yaphone
	 * @date 2017年4月20日 上午12:15:00
	 * @param msg
	 * @return
	 */
	public String textMsgHandle(BaseMsg msg);

	/**
	 * 处理图片消息
	 * 
	 * @author https://github.com/yaphone
	 * @date 2017年4月21日 下午11:07:06
	 * @param msg
	 * @return
	 */
	public String picMsgHandle(BaseMsg msg);

	/**
	 * 处理声音消息
	 * 
	 * @author https://github.com/yaphone
	 * @date 2017年4月22日 上午12:09:44
	 * @param msg
	 * @return
	 */
	public String voiceMsgHandle(BaseMsg msg);

	/**
	 * 处理小视频消息
	 * 
	 * @author https://github.com/yaphone
	 * @date 2017年4月23日 下午12:19:50
	 * @param msg
	 * @return
	 */
	public String viedoMsgHandle(BaseMsg msg);

	/**
	 * 处理名片消息
	 * 
	 * @author https://github.com/yaphone
	 * @date 2017年5月1日 上午12:50:50
	 * @param msg
	 * @return
	 */
	public String nameCardMsgHandle(BaseMsg msg);

	/**
	 * 处理系统消息
	 * 
	 * @author Relyn
	 * @date 2017年6月21日17:43:51
	 * @param msg
	 * @return
	 */
	public void sysMsgHandle(BaseMsg msg);

	/**
	 * 处理确认添加好友消息
	 * 
	 * @date 2017年6月28日 下午10:15:30
	 * @param msg
	 * @return
	 */
	public String verifyAddFriendMsgHandle(BaseMsg msg);

	/**
	 * 处理收到的文件消息
	 * 
	 * @date 2017年7月21日 下午11:59:14
	 * @param msg
	 * @return
	 */
	public String mediaMsgHandle(BaseMsg msg);

}

在每个接口方法中，需要处理的消息均为上面介绍的BaseMsg的POJO类，在textMsgHandler中，通过msg.getText()就可以获取收到的文本信息，然后作进一步处理，比如接入图灵机器人、消息自动回复等，我们需要在这个方法中返回一个字符串，即是需要回复给好友的消息，在SimpleDemo这个示例中，我们直接回复收到的原文本消息。

在picMsgHandle、voiceMsgHandle、viedoMsgHandle这三个方法中，我们需要将这些消息下载下来，然后再作进一步处理，所以需要为每种类型的消息提供一个保存路径，然后调用DownloadTools.getDownloadFn方法可以将这三种类型的消息下载下来。DownloadTools.getDownloadFn方法提供下载图片、语音、小视频的功能，需要三个参数，第一个参数为我们收到的msg，第二个参数为MsgType，也就是消息类型，图片、语音、小视频分别对应MsgTypeEnum.PIC.getType()、MsgTypeEnum.VOICE.getType()、MsgTypeEnum.VIEDO.getType()，然后第三个参数就是保存这些消息的路径了。

另外还有一些需要处理的其它消息，如系统消息、名片消息、处理好友请求消息等，按业务需求进行实现即可。

就不多说了，让代码和注释君自述吧，有不明白的地方，可以在Issue中提出来。

package cn.zhouyafeng.itchat4j.demo.demo1;

import java.io.File;
import java.text.SimpleDateFormat;
import java.util.Date;

import org.apache.log4j.Logger;

import cn.zhouyafeng.itchat4j.api.MessageTools;
import cn.zhouyafeng.itchat4j.api.WechatTools;
import cn.zhouyafeng.itchat4j.beans.BaseMsg;
import cn.zhouyafeng.itchat4j.beans.RecommendInfo;
import cn.zhouyafeng.itchat4j.core.Core;
import cn.zhouyafeng.itchat4j.face.IMsgHandlerFace;
import cn.zhouyafeng.itchat4j.utils.enums.MsgTypeEnum;
import cn.zhouyafeng.itchat4j.utils.tools.DownloadTools;

/**
 * 简单示例程序，收到文本信息自动回复原信息，收到图片、语音、小视频后根据路径自动保存
 * 
 * @author https://github.com/yaphone
 * @date 创建时间：2017年4月25日 上午12:18:09
 * @version 1.0
 *
 */
public class Simpl