Package Exports

wechaty

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (wechaty) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Wechaty

Wechaty is a Chatbot Library for Wechat Personal Account.

Easy creating personal account wechat robot in 9 lines of code.

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: 9 lines

The following 9 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(`Use Wechat to scan qrcode in url to login: ${code}\n${url}`)
}).on('message', m => {
  bot.send(m.reply('roger'))                              // 1. reply
  .then(() => console.log(`RECV: ${m}, REPLY: "roger"`))  // 2. log message
  .catch(e => console.error(e))                           // 3. catch exception
})

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: dozens of lines

Here's an chatbot ding-dong-bot who can reply dong when receives a message ding.

3. Hardcore: hundreds of lines

Here's a chatbot api-ai-bot, who can slightly understand NLP.

Natual Language Understanding enabled by api.AI, you can get your module on api.AI by it's free plan.

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.

Visit Node.js
Download NodeJS Installer(i.e. "v6.2.0 Current")
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

Wechaty support the following 5 events:

scan
login
logout
message
error

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.` )
})

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

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.

5. Event: `error`

To be support.

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:

id :String
from :Contact
to :Contact
content :String
group :Group
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.
})

Message.reply()

Create a new Message instance that reply the original one. which means: the to field of the reply message is the from of origin message.

const replyMessage = message.reply('roger!')
bot.send(replyMessage)

Class Contact

Contact.get(prop)

Get prop from a contact.

Supported prop list:

id :String
weixin :String
name :String
remark :String
sex :Number
province :String
city :String
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:

id :String
name :String
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.10 (2016/5/28)

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

v0.0.5 (2016/5/11)

Receive & send message
Show contacts info
Show groups info
1st usable version
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
Session save/load

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).

wechaty

Package Exports

Readme

Wechaty

Why

Examples

1. Basic: 9 lines

2. Advanced: dozens of lines

3. Hardcore: hundreds of lines

Installation

Install from NPM

Install from Github(for hack)

1. Install Node.js

2. Fork & Clone Wechaty

3. Run Demo Bot

4. Done

Trouble Shooting

Requirement

API Refference

Events

1. Event: scan

2. Event: login

3. Event: logout

4. Event: message

5. Event: error

Class Wechaty

Wechaty.init()

Class Message

Message.get(prop)

Message.set(prop, value)

Message.ready()

Message.reply()

Class Contact

Contact.get(prop)

Contact.ready()

Class Group

Group.get(prop)

Group.ready()

Test

Version History

v0.0.10 (2016/5/28)

v0.0.5 (2016/5/11)

Todo List

Known Issues & Support

Contributing

See Also

Other Library

Javascript

Perl

Python

Chat Script

Application

Service

Framework

Author

Copyright & License

1. Event: `scan`

2. Event: `login`

3. Event: `logout`

4. Event: `message`

5. Event: `error`