Awesome

jeeves

A smart WeChat bot.

中文文档

Getting Started

Requirements

JDK 8

How to run

mvn spring-boot:run

You should see the following logs.

After scanning and confirming login

Login process

Example

com.cherry.jeeves.MessageHandlerImpl is provided as an example of jeeves. You can modify the code in MessageHandlerImpl yourself or create another Spring Bean of MessageHandler to meet your requirements.

The default behaviors that are set in MessageHandlerImpl are:

• Auto-save thumb images in image messages to local disk.
• Auto-reply plain text messages.
• Accept all friend invitations.
• After accepting friend invitations, set alias to the friend.
• Log for all other events.

Usages

Events

A bean that implements MessageHandler will be notified on all the following events.

Text message

void onReceivingPrivateTextMessage(Message message);

Image message

void onReceivingPrivateTextMessage(Message message, String thumbImageUrl, String fullImageUrl);

ChatRoom text message

void onReceivingChatRoomTextMessage(Message message);

ChatRoom image message

void onReceivingChatRoomImageMessage(Message message, String thumbImageUrl, String fullImageUrl);

Received a friend invitation

boolean onReceivingFriendInvitation(RecommendInfo info);

Callback after accepting a friend invitation

boolean postAcceptFriendInvitation(Message message);

New chatrooms found

void onNewChatRoomsFound(Set<Contact> chatRooms);

Chatrooms deleted

void onChatRoomsDeleted(Set<Contact> chatRooms);

Members changed in a chatroom

void onChatRoomMembersChanged(Contact chatRoom, Set<ChatRoomMember> membersJoined, Set<ChatRoomMember> membersLeft);

New friends found

void onNewFriendsFound(Set<Contact> contacts);

Friends deleted

void onFriendsDeleted(Set<Contact> contacts);

New media platforms found

void onNewMediaPlatformsFound(Set<Contact> mps);

Media platforms deleted

void onMediaPlatformsDeleted(Set<Contact> mps);

Red packet received

void onRedPacketReceived(Contact contact);

API

WechatHttpService has provided a bundle of apis that you can use to interact with the server.

Get all the contacts

Set<Contact> getContact()

Get all the members in given chatrooms

Set<Contact> batchGetContact(Set<String> list)

Send plain text

void sendText(String userName, String content)

Set alias to given contact

void setAlias(String userName, String newAlias)

logout

void logout()

Create a chatroom

void createChatRoom(String[] userNames, String topic)

Invite a contact to a certain chatroom

void addChatRoomMember(String chatRoomUserName, String userName)

Delete a contact from a certain chatroom (if you're the owner!)

void deleteChatRoomMember(String chatRoomUserName, String userName)

Download images in the conversation

Note that it's better not to download image directly. This method has included cookies in the request.

byte[] downloadImage(String url)

FAQ

Q: What protocols is jeeves running on?

A: Jeeves is running on WeChat web protocols.

Q: How is jeeves different from other WeChat bots?

A: Jeeves is aimed to disguise itself as a normal web WeChat app. So we value details. Jeeves not only submits requests which are essential to login process, but also submits those are used for cross-platform status synchronization, status report and so on. The more details jeeves imitate, the safer your account is. Jeeves provides the following imitations.

• Jeeves starts login process with requesting the login page (default as https://wx.qq.com) while most other bots skip directly to getting uuid.
• Jeeves stores all the cookies carefully. It evens brings cookies in a request for getting images, which makes the request look like it's from a real browser.
• During the login process, when the QR code is expired, jeeves will start over the whole login process to get a new QR code. But in the following requests, a refreshTimes cookie is inserted, which indicates how many times that jeeves has started over. This is the way a real web WeChat app works.
• Jeeves knows how to generate a random code/timestamp just as web WeChat do. We've studied some javascript code of web WeChat.
• A statusNotify request with StatusNotifyCode.READED is used to notify the mobile WeChat app that all the messages in a given conversation have been read. Jeeves takes care of it for you. When you send a plain text message to a contact, jeeves would check if there're any unread messages in the conversation between you and the contact. If true, jeeves will first send out statusNotify to mark all these message read prior to the message request, which makes sense in a real world case.

Q: What can I do using jeeves?

A: Jeeves is a perfect tool if you'd like to store all the messages locally. As a mischief, you can send the messages that others have recalled back to chatroom. Use your imagination!

Q: What can't jeeves do?

A: Jeeves is still in masterelopment. Some complicated features such as sending an image is still in the todo list. Find all the available events and apis in the Usages.

Q: Can jeeves prevent itself from disconnecting from server?

A: Jeeves can't guarantee it. We're still working on it. Usually jeeves can stay for hours, up to 2 days. To stay connected as long as possible, DON'T have any unusual behaviors that real humans don't have. For example, sending 100 messages in one second.

Q: Why is my account blocked on web WeChat?

A: It depends on lots of factors. Tencent has statistics of all the behaviors and data of your account. Some unusual behaviors would put your account in risk. For example, sending messages to a person doesn't exist or you're not allowed to chat with. Additionally, Tencent has a list of the limits on all kinds of actions that an account can take. If your account exceeds the boundary, it could be blocked. For example, too many times of login in a short time.

Known Issues

• Jeeves is using ZXing for printing QR in terminal. It's seldom that com.google.zxing.NotFoundException is thrown. We're still investigating into it. To workaround it, just restart jeeves.

Warning

Using any WeChat bots, including jeeves, could cause your account be blocked. It's at your own risk.

Credits

Jeeves project is inspired by ItChat and WeixinBot.

Bugs and Feedback

For bugs, questions and discussions please use the Github Issues.

License

MIT