Wechaty
Connecting ChatBots.
Wechaty is a Bot Framework for Wechat Personal Account that help you easy creating personal wechat bot in 7 lines of javascript code, with cross platform support to linux, win32 and darwin(OSX/Mac).
https://github.com/wechaty/wechaty
🪲 https://github.com/wechaty/wechaty/issues
📖 https://github.com/wechaty/wechaty/wiki
🐳 https://hub.docker.com/r/zixia/wechaty
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
@Samurais wechaty is great. 👍 link
Examples
Wechaty is dead easy to use: 7 lines javascript for your 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', message => console.log(`Message: ${message}`))
.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" wechaty/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 .
Ship
Wechaty can be used via: Container as a Service
- Arukas Cloud - Hosting Docker Containers(Currently in Beta, provide up to 10 free containers)
- Docker Cloud - Docker Cloud is a hosted service that provides a Registry with build and testing facilities for Dockerized application images, tools to help you set up and manage your host infrastructure, and deployment features to help you automate deploying your images to your infrastructure.
- Dao Cloud - 容器云平台
Deploy with Heroku
To Be Fix
Follow these instructions. Then, ![Deploy to Heroku](https://www.herokucdn.com/deploy/button.sv
g)
Installation
Install from NPM
Use NPM is recommended to install a stable version of Wechaty published on NPM.com
npm install --save wechaty
If you use chrome instead of phantomjs, you should make sure:
- chrome is installed
- if you are under linux, set headless right for
Xvfb
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
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/wechaty/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.
Wechaty Badge
Markdown
[![Powered by Wechaty](https://img.shields.io/badge/Powered%20By-Wechaty-green.svg)](https://github.com/wechaty/wechaty)
Html
<a href="https://github.com/wechaty/wechaty" target="_blank">
<img src="https://img.shields.io/badge/Powered%20By-Wechaty-green.svg" alt="Powered by Wechaty" border="0">
</a>
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
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:
silly
verbose
info
warn
error
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
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:
- 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:
- scan
- login
- logout
- message
- error
scan
1. Event: 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:
- 0 initial
- 200 login confirmed
- 201 scaned, wait for confirm
- 408 wait for scan
scan
event will be emit when it will detect a new code status change.
login
2. Event: 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`)
})
logout
3. Event: 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`)
})
message
4. Event: Emit when there's a new message.
wechaty.on('message', message => {
console.log('message ${message} received')
})
The message
here is a Message.
error
5. Event: To be support.
friend
6. Event: Fired when we got new friend request, or confirm a friend ship.
wechaty.on('friend', (contact: Contact, request: FriendRequest) => {
if (request) { // 1. request to be friend from new contact
request.accept()
console.log('auto accepted for ' + contact + ' with message: ' + request.hello)
} else { // 2. confirm friend ship
console.log('new friend ship confirmed with ' + contact))
}
})
Class Wechaty
Main bot class.
const bot = new Wechaty({
profile
, token
})
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
- can be set by environment variable:
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:
id
:Stringfrom
:Contactto
:Contactcontent
:Stringroom
:Roomdate
: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:
id
:Stringweixin
:Stringname
:Stringremark
:Stringsex
:Numberprovince
:Stringcity
:Stringsignature
: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:
id
:Stringname
:Stringmembers
:Arraycontact
:Contactname
: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.
})
Class FriendRequest
Send, receive friend request, and friend confirmation events.
When someone send you a friend request, there will be a Wechaty friend
event fired.
wechaty.on('friend', (contact: Contact, request: FriendRequest) => {
if (request) { // 1. request to be friend from new contact
request.accept()
console.log('auto accepted for ' + contact + ' with message: ' + request.hello)
} else { // 2. confirm friend ship
console.log('new friend ship confirmed with ' + contact))
}
})
Talk is cheap, show me the code: Example/Friend-Bot
FriendRequest.hello: string
verify message
FriendRequest.accept(): void
accept a friend request
FriendRequest.send(contact: Contact, hello: string): void
send new friend request
const from = message.get('from')
const request = new FriendRequest()
request.send(from, 'hello~')
Test
Wechaty use TAP protocol AVA 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
master
- #32 Extend Room Class with:
- tbw
- #33 New Class
FriendRequest
with: Wechaty.on('friend', (contact, request) => {})
with Wechaty new Eventfriend
accept()
to accept a friend requestsend()
to send new friend request
v0.3.13 (2016/09)
- Managed by Cloud Manager: https://app.wechaty.io
- Dockerized & Published to docker hub as: zixia/wechaty
- Add
reset
&shutdown
to IO Event - Switch Unit Test Runner from Tape/Tap to AVA
- Move git resposity from zixia/wechaty to wechaty/wechaty
v0.2.3 (2016/7/28)
- add wechaty.io cloud management support: set environment variable
WECHATY_TOKEN
to enable io support - rename
WECHATY_SESSION
toWECHATY_PROFILE
for better name - fix watchdog timer & reset bug
v0.1.8 (2016/6/25)
- add a watchdog to restore from unknown state
- add support to download image message by
ImageMessage.readyStream()
- fix lots of stable issues with webdriver exceptions & injection js code compatible
v0.1.1 (2016/6/10)
- add support to save & restore wechat login session
- add continious integration tests on win32 platform. (powered by AppVeyor)
- add environment variables HEAD/PORT/SESSION/DEBUG to config Wechaty
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
message
message.recv
message.sent
message.recv.image
message.sent.image
message.recv.sys
message.**.image
message.recv.*
- Use EventEmitter2 to emit message events, so we can use wildcard
- Message
- Send/Reply image/video/attachment message
- Save video message to file
- Save image message to file
- Session save/load
- Rewrite to TypeScript
- Switch to AVA Test Runner
Everybody is welcome to issue your needs.
Known Issues & Support
Github Issue https://github.com/wechaty/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
- Weixinbot Nodejs 封装网页版微信的接口,可编程控制微信消息
- wechatBot 面向个人的微信 wechat 机器人平台 - 使用微信网页版接口wechat4u
- Wechat4U 微信 wechat web 网页版接口的 JavaScript 实现,兼容Node和浏览器
- wechat-user-bot 正在组装中的微信机器人
Electron
Go
- 0d0f/exfe Wechat bot component of exfe-bus
Perl
- MojoWeixin 使用Perl语言编写的微信客户端框架,基于Mojolicious,要求Perl版本5.10+,可通过插件提供基于HTTP协议的api接口供其他语言或系统调用
Python
- WeixinBot Very well documented 网页版微信API,包含终端版微信及微信机器人
- wxBot: Wechat Bot API
- ItChat: 微信个人号接口(支持文件、图片上下载)、微信机器人及命令行微信。三十行即可自定义个人号机器人
- WechatIrcd: 用IRC客户端控制微信网页版
- 查看被删的微信好友: 由于微信后台已经对此类脚本做了屏蔽,无论是什么语言版本的脚本均已经失效,此项目帮助了解微信web版通讯过程,切勿再使用!
KDE
dotNET
- WeChat.NET WeChat.NET client based on web wechat
Chat Script
- SuperScript A dialog system and bot engine for conversational UI's. (Pure Javascript)
- RiveScript A simple scripting language for giving intelligence to chatbots and other conversational entities. (Perl original, Multi-Language support)
- CleverScript Easily create text, voice or avatar bots that people can chat with in browser, app or their preferred messaging platform.
Application
- 助手管家 It's a Official Account of wechat, which can manage your personal wechat account as a robot assistant.
Service
- Luis.ai Language Understanding Intelligent Service (LUIS) offers a fast and effective way of adding language understanding to applications from Microsoft
- API.ai Build conversational user interfaces
- Wit.ai Turn user input into action from Facebook
- 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
- 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