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

Connecting ChatBots.

Wechaty is a Chatbot Library for Wechat Personal Account. (Supports Linux, Win32 and OSX)

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

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 rooms 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 room). ;-)

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 wechaty = new Wechaty()
wechaty.init().on('scan', ({url, code}) => {
  console.log(`Use Wechat to scan qrcode in url to login: ${code}\n${url}`)
}).on('message', m => {
  !m.self() && wechaty.reply(m, '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 to Cloud9 IDE

Cloud9 IDE is Google Docs for Code.

Cloud9 IDE written in JavaScript, uses Node.js on the back-end. It uses Docker containers for its workspaces, and hosted on Google Compute Engine.

1. Open Cloud9 IDE

Just one click here:

2. Set default to Node.js v6

Open Terminal in Cloud9 IDE, use nvm to install nodejs v6, which is required by Wechaty.

$ nvm install 6
Downloading https://nodejs.org/dist/v6.2.1/node-v6.2.1-linux-x64.tar.xz...
######################################################################## 100.0%
Now using node v6.2.1 (npm v3.9.3)

$ nvm alias default 6
default -> 6 (-> v6.2.1)

$ node --version
v6.2.1

3. Run

$ npm install

$ node example/ding-dong-bot.js

4. Enjoy Cloud9 IDE

You are set.

Install from Github

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

DEBUG output

Wechaty use npmlog to output debug message. You can set log level by environment variable WECHATY_DEBUG to show debug message.

environment variable WECHATY_DEBUG values:

silly
verbose
info
warn
error

Linux/OSX(Mac):

$ export WECHATY_DEBUG=verbose

Win32:

set WECHATY_DEBUG=verbose

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.

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

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

wechaty.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 wechaty = new Wechaty(options)

options:

session(OPTIONAL): session name. if a session name is provided, the login status will be saved to it, and automatically restored on next time of wechaty start(restart).
- can be set by environment variable: WECHATY_SESSION
head(OPTIONAL): specify the browser name for webdriver.
- can be set by environment variable: WECHATY_HEAD
- values:
  - phantomjs: it's the default behaviour if head is not set.
  - chrome

Wechaty.init()

Initialize the bot, return Promise.

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

Wechaty.reply(message: Message, reply: String)

Reply a message with reply.

That means: the to field of the reply message is the from of origin message.

wechaty.reply(message, 'roger')

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
room :Room
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.self()

Check if message is send by self.

Return true for send from self, false for send from others.

if (m.self()) {
  console.log('this message is sent by myself!')
}

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 Room

Room.get(prop)

Get prop from a room.

Supported prop list:

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

room.get('members').length

Room.ready()

A room 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.

room.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.1.1 (2016/6/10)

add support session save & restore
add continious integration tests on Win32 platform. (powered by AppVeyor)
add use environment variables to config HEAD/PORT/SESSION/DEBUG

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 rooms 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 Room
- Create a new chat room
- Invite people to join a existing chat room
- Rename a Chat Room
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 to Cloud9 IDE

1. Open Cloud9 IDE

2. Set default to Node.js v6

3. Run

4. Enjoy Cloud9 IDE

Install from Github

1. Install Node.js

2. Fork & Clone Wechaty

3. Run Demo Bot

4. Done

Trouble Shooting

DEBUG output

Requirement

API Refference

Events

1. Event: scan

2. Event: login

3. Event: logout

4. Event: message

5. Event: error

Class Wechaty

Wechaty.init()

Wechaty.reply(message: Message, reply: String)

Class Message

Message.get(prop)

Message.set(prop, value)

Message.ready()

Message.self()

Class Contact

Contact.get(prop)

Contact.ready()

Class Room

Room.get(prop)

Room.ready()

Test

Version History

v0.1.1 (2016/6/10)

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`