ccdos / wechaty

Wechat for Bot. Powered by WebDriver & Node.js

Wechaty

Connecting ChatBots.

Wechaty is a Bot Framework for Wechat Personal Account.

Easy creating personal wechat bot in 9 lines of code.

It supports linux, win32 and darwin(OSX/Mac).

Voice of the Developer

@GasLin : it may be the best wecaht sdk i have seen in github! link

@ak5 : Thanks for this it's quite cool! link

@ccaapton : wechaty library looks fantastic! link

Examples

Wechaty is dead easy to use: 7 lines javascript for your 1st wechat bot.

1. Basic: 7 lines

The following 7 lines of code implement a bot who can log all message to console:

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

bot
.on('scan', ({url, code}) => console.log(`Scan QrCode to login: ${code}\n${url}`))
.on('login',         user => console.log(`User ${user} logined`))
.on('message',          m => console.log(`Message: ${m}`))
.init()

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.

Deploy

Use docker to deploy wechaty is highly recommended.

Deploy with Docker

Wechaty is fully dockerized. So it will be very easy to be deployed as a MicroService.

$ export TOKEN="your token here"

$ docker run -e WECHATY_TOKEN="$TOKEN" zixia/wechaty

WECHATY_TOKEN is required here, because you need this key to manage wechaty on the chatbot cloud manager: https://www.wechaty.io

Build

$ docker build -t wechaty .

Deploy with Heroku

To Be Fix

Follow these instructions. Then, 

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, which is my favourite IDE today. Almost all my wechaty development is based on Cloud9.

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

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

To test with full log messages

$ WECHATY_LOG=silly npm test

Details about unit testing

LOG output

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

environment variable WECHATY_LOG values:

1. silly
2. verbose
3. info
4. warn
5. error
6. silent for disable logging

Linux/Darwin(OSX/Mac):

$ export WECHATY_LOG=verbose

Win32:

set WECHATY_LOG=verbose

Tips: You may want to have more scroll buffer size in your CMD window in windows.

mode con lines=32766

http://stackoverflow.com/a/8775884/1123955

NpmLog with Timestamp

Here's a quick and dirty patch, to npmlog/log.js

  m.message.split(/\r?\n/).forEach(function (line) {

    var date = new Date();
    var min = date.getMinutes()
    var sec = date.getSeconds()
    var hour = date.getHours()

    if (sec < 10) { sec = '0' + sec }
    if (min < 10) { min = '0' + min }
    if (hour < 10) { hour = '0' + hour }

    this.write(hour + ':' + min + ':' + sec + ' ')

    if (this.heading) {
      this.write(this.heading, this.headingStyle)
      this.write(' ')
    }

And we can looking forward the official support from npmlog: npm/npmlog#24

DEBUG

set environment variable WECHATY_DEBUG to enable DEBUG in Wechaty.

this will:

1. open phantomjs debugger port on 8080

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:

1. scan
2. login
3. logout
4. message
5. 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.` )
})

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

3. Event: logout

logout will be emitted when bot detected it is logout, with a Contact of current logined user.

wechaty.on('logout', user => {
  console.log(`user ${user} 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 bot = new Wechaty({
  profile
  , token
})

1. profile(OPTIONAL): profile name. if a profile 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_PROFILE
2. token(OPTIONAL): wechaty io token. Be used to connect to cloud bot manager.

Wechaty.init(): Wechaty

Initialize the bot, return Promise.

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

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

Reply a message with reply.

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

wechaty.reply(message, 'roger')

Wechaty.self(): boolean

Check if message is send by self.

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

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

Class Message

All wechat messages will be encaped as a Message.

Message.get(prop): String|Contact|Room|Date

Get prop from a message.

Supported prop list:

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

message.get('content')

Message.set(prop, value): Message

Set prop to value for a message.

Supported prop list: the same as get(prop)

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

Message.ready(): Message

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): String|Number

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(): Contact

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): String|Array[{contact: Contact, name: String}]

Get prop from a room.

Supported prop list:

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

room.get('members').length

Room.ready(): Room

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.3.2 (master)

1. Managed by Cloud Manager: https://app.wechaty.io
2. Dockerized & Published to docker hub as: zixia/wechaty
3. add reset & shutdown to IO Event

v0.2.3 (2016/7/28)

1. add wechaty.io cloud management support: set environment variable WECHATY_TOKEN to enable io support
2. rename WECHATY_SESSION to WECHATY_PROFILE for better name
3. fix watchdog timer & reset bug

v0.1.8 (2016/6/25)

1. add a watchdog to restore from unknown state
2. add support to download image message by ImageMessage.readyStream()
3. fix lots of stable issues with webdriver exceptions & injection js code compatible

v0.1.1 (2016/6/10)

1. add support to save & restore wechat login session
2. add continious integration tests on win32 platform. (powered by AppVeyor)
3. add environment variables HEAD/PORT/SESSION/DEBUG to config Wechaty

v0.0.10 (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 rooms 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 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/video/attachment message
  • Save video message to file
  • Save image message to file
• 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).

See Also

Similar Project

Javascript

1. Weixinbot Nodejs 封装网页版微信的接口，可编程控制微信消息
2. wechatBot 面向个人的微信 wechat 机器人平台 - 使用微信网页版接口wechat4u
3. Wechat4U 微信 wechat web 网页版接口的 JavaScript 实现，兼容Node和浏览器
4. wechat-user-bot 正在组装中的微信机器人

Perl

1. MojoWeixin 使用Perl语言编写的微信客户端框架，基于Mojolicious，要求Perl版本5.10+，可通过插件提供基于HTTP协议的api接口供其他语言或系统调用

Python

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

Chat Script

1. SuperScript A dialog system and bot engine for conversational UI's. (Pure Javascript)
2. RiveScript A simple scripting language for giving intelligence to chatbots and other conversational entities. (Perl original, Multi-Language support)

Application

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

Service

1. Luis.ai Language Understanding Intelligent Service (LUIS) offers a fast and effective way of adding language understanding to applications from Microsoft
2. API.ai Build conversational user interfaces
3. Wit.ai Turn user input into action from Facebook
4. Watson a comprehensive, robust, platform for managing conversations between virtual agents and users through an application programming interface (API) from IBM

• Advanced Natural Language Processing Tools for Bot Makers a good article of comparing the above services.

Framework

1. Bot Framework Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services. from Microsoft

My Story

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

At last, It's built for my personal study purpose of Automatically Testing.

Author

Zhuohuan LI [email protected] (http://linkedin.com/in/zixia)

Copyright & License

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