Wechaty

Wechaty is a Bot-Enable Framework/Library for Personal Account of Wechat.

Easy creating personal account wechat robot code in 10 lines.

Connecting Bots

Why

My daily life/work depends on too much chat on wechat.

• I almost have 14,000 wechat friends till May 2014, before wechat restricts a total number of friends to 5,000.
• I almost have 400 wechat groups that most of them have more than 400 members.

Can you image that? I'm dying...

So a tireless bot working for me 24x7 on wechat, moniting/filtering the most important message is badly needed. For example: highlights discusstion which contains the KEYWORDS I want to follow up(especially in a noisy group). ;-)

Examples

Wechaty is super easy to use: 10 lines of javascript is enough for your first wechat robot.

1. Basic: 10 lines

The following 10 lines of code implement a bot who reply "roger" for every message received:

const Wechaty = require('wechaty')
const bot = new Wechaty()

bot.init()
.on('scan', ({url, code}) => {
  console.log(`Scan qrcode in url to login: ${code}\n${url}`)
})
.on('message', m => {
  console.log('RECV: ' + m.get('content'))  // 1. print received message

  const reply = new Wechaty.Message()       // 2. create reply message
  .set('to', m.get('from'))                 //    1) set receipt
  .set('content', 'roger.')                 //    2) set content

  bot.send(reply)                           // 3. do reply!
  .then(() => console.log('REPLY: roger.')) // 4. print reply message
})

Notice that you need to wait a moment while bot trys to get the login QRCode from Wechat. As soon as the bot gets login QRCode url, he will print url out. You need to scan the qrcode on wechat, and confirm login.

After that, bot will be on duty. (roger-bot source can be found at here)

2. Advanced: 50 lines

There's another basic usage demo bot named ding-dong-bot, who can reply dong when bot receives a message ding.

3. Hardcore: 100 lines

To Be Written.

Plan to glue with Machine Learning/Deep Learning/Neural Network/Natural Language Processing.

Installation

Install from NPM

Use NPM is recommended to install a stable version of Wechaty published on NPM.com

npm install --save wechaty

Then you are set.

Install from Github(for hack)

In case that you want to dive deeper into Wechaty, fork & clone to run Wechaty bot on your machine, and start hacking.

1. Install Node.js

Node.js Version 6.0 or above is required.

1. Visit Node.js
2. Download NodeJS Installer(i.e. "v6.2.0 Current")
3. Run Installer to install NodeJS to your machine

2. Fork & Clone Wechaty

If you have no github account, you can just clone it via https:

git clone https://github.com/zixia/wechaty.git

This will clone wechaty source code to your current directory.

3. Run Demo Bot

cd wechaty
npm install
npm start

This will run node example/ding-dong-bot.js

After a little while, bot will show you a message of a url for Login QrCode. You need to scan this qrcode in your wechat in order to permit your bot login.

4. Done

Enjoy hacking Wechaty! Please submit your issue if you have any, and a fork & pull is very welcome for showing your idea.

Trouble Shooting

If wechaty is not run as expected, run unit test maybe help to find some useful message.

npm test

Requirement

ECMAScript2015(ES6). I develop and test wechaty with Node.js v6.0.

API Refference

I'll try my best to keep the api as sample as it can be.

Events

1. Event: scan

A scan event will be emitted when the bot need to show you a QrCode for scaning.

bot.on('scan', ({code, url}) => {
  console.log(`[${code}] Scan ${url} to login.` )
})

1. url: {String} the qrcode image url
2. code: {Number} the scan status code. some known status of the code list here is:
   1. 0 initial
   2. 408 wait for scan
   3. 201 scaned, wait for confirm
   4. 200 login confirmed

scan event will be emit when it will detect a new code status change.

2. Event: login

After the bot login full successful, the event login will be emitted, with a Contact of current logined user.

bot.on('login', user => {
  console.log(`user ${user} logined`)
})

3. Event: logout

logout will be emitted when bot detected it is logout.

4. Event: message

Emit when there's a new message.

bot.on('message', message => {
  console.log('message ${message} received')
})

The message here is a Message.

Class Wechaty

Main bot class.

const bot = new Wechaty()

Wechaty.init()

Initialize the bot, return Promise.

bot.init()
.then(() => {
  // do other staff with bot here
}

Class Message

All wechat messages will be encaped as a Message.

Message.get(prop)

Get prop from a message.

Supported prop list:

1. id :String
2. from :Contact
3. to :Contact
4. content :String
5. group :Group
6. date :Date

message.get('content')

Message.set(prop, value)

Set prop to value for a message.

Supported prop list: the same as get(prop)

message.set('content', 'Hello, World!')

Message.ready()

A message may be not fully initialized yet. Call ready() to confirm we get all the data needed.

Return a Promise, will be resolved when all data is ready.

message.ready()
.then(() => {
  // Here we can be sure all the data is ready for use.
})

Class Contact

Contact.get(prop)

Get prop from a contact.

Supported prop list:

1. id :String
2. weixin :String
3. name :String
4. remark :String
5. sex :Number
6. province :String
7. city :String
8. signature :String

contact.get('name')

Contact.ready()

A Contact may be not fully initialized yet. Call ready() to confirm we get all the data needed.

Return a Promise, will be resolved when all data is ready.

contact.ready()
.then(() => {
  // Here we can be sure all the data is ready for use.
})

Class Group

Group.get(prop)

Get prop from a group.

Supported prop list:

1. id :String
2. name :String
3. members :Array
   1. contact :Contact
   2. name :String

group.get('members').length

Group.ready()

A group may be not fully initialized yet. Call ready() to confirm we get all the data needed.

Return a Promise, will be resolved when all data is ready.

group.ready()
.then(() => {
  // Here we can be sure all the data is ready for use.
})

Test

Wechaty use TAP protocol to test itself by tap.

To test Wechaty, run:

npm test

Know more about TAP: Why I use Tape Instead of Mocha & So Should You

Version History

v0.0.9 (2016/5/28)

1. use event scan to show login qrcode image url(and detect state change)
2. new examples: Tuling123 bot & api.AI bot
3. more unit tests
4. code coverage status

v0.0.5 (2016/5/11)

1. Receive & send message
2. Show contacts info
3. Show groups info
4. 1st usable version
5. Start coding from May 1st 2016

Todo List

• Contact
  • Accept a friend request
  • Send a friend request
  • Delete a contact
• Chat Group
  • Create a new chat group
  • Invite people to join a existing chat group
  • Rename a Chat Group
• Events
  • Use EventEmitter2 to emit message events, so we can use wildcard
    1. message
    2. message.recv
    3. message.sent
    4. message.recv.image
    5. message.sent.image
    6. message.recv.sys
    7. message.**.image
    8. message.recv.*
• Message
  • Send/Reply image message

Everybody is welcome to issue your needs.

Known Issues & Support

Github Issue - https://github.com/zixia/wechaty/issues

Contributing

• Lint: eslint

  $ npm lint

• Create an issue, fork, then send a pull request(with unit test please).

See Also

Javascript

1. Weixinbot Nodejs 封装网页版微信的接口，可编程控制微信消息

Python

1. WeixinBot Very well documented 网页版微信API，包含终端版微信及微信机器人
2. wxBot: Wechat Bot API
3. ItChat: 微信个人号接口（支持文件、图片上下载）、微信机器人及命令行微信。三十行即可自定义个人号机器人

Apps

1. 助手管家 It's a Official Account of wechat, which can manage your personal wechat account as a robot assistant.

Bot API Service

1. IBM Watson Dialog Service a comprehensive, robust, platform for managing conversations between virtual agents and users through an application programming interface (API)
2. API.ai Build conversational user interfaces
3. Wit.ai Turn user input into action

Author

Zhuohuan LI zixia@zixia.net (http://linkedin.com/in/zixia)

Copyright & License

• Code & Docs 2016© zixia
• Code released under the ISC license
• Docs released under Creative Commons