Wechaty

Connecting ChatBots.

Wechaty is a Bot Framework for Wechat Personal Account that helps you easy creating bot in 6 lines of javascript, with cross-platform support to Docker 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

Wechaty had rewritten to Typescript.

Details: wechaty#40

+ Typescriptilized ...
+ on 12th Oct 2016

VSCode is recommended as developing IDE for typescript because we can get the benefit of intelligent code completion, parameter info, and member lists.

The last Javascript version is: v0.4.0 (2016/10/9) , or install v0.4 by npm install wechaty.

Benifits from Typescript

Voice of the Developer

@JasLin : it may be the best wechat SDK I have seen in Github! link

@ccaapton : wechaty library fantastic! link

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

@Samurais : wechaty is great. link

@Jarvis : 目前用过的最好的微信开发库 link

@naishstar : thanks for great SDK link

Examples

Wechaty is dead easy to use: 6 lines javascript for your wechat bot.

1. Basic: 6 lines

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

import Wechaty from 'wechaty'

Wechaty.instance() // Singleton
.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 tries 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 QR code on wechat and confirm login.

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

2. Advanced: dozens of lines

Here's a 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.

Natural Language Understanding enabled by api.AI, you can get your module on api.AI by its 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 managing 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 the 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

Running a GUI application in a Docker container

Then you are set.

Install to Cloud9 IDE

Cloud9 IDE is Google Docs for Code, which is my favorite 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

$ npm run demo

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
npm run demo

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

4. Done

Setup `Xvfb` in linux

How to Install & Run Wechaty in Linux Server by @lijiarui

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

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.

the 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

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

I'll try my best to keep the API as simple as it can be.

Events

Wechaty supports the following 6 events:

scan
login
logout
message
error
friend
room-join
room-leave
room-topic

this.say(content: string)

this is Sayable for all listeners. here this is a Wechaty instance.

this.say() method will sending message to filehelper, just for logging / reporting / any usage for your convenience

1. Event: `scan`

A scan event will be emitted when the bot needs to show you a QR Code for scanning.

wechaty.on('scan', (this: Sayable, url: string, code: number) => {
  console.log(`[${code}] Scan ${url} to login.` )
})

URL: {String} the QR code 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 waits for scan

scan event will be emitted 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', (this: Sayable, user: Contact) => {
  console.log(`user ${user} login`)
})

3. Event: `logout`

logout will be emitted when bot detected logout, with a Contact of the current login user.

wechaty.on('logout', (this: Sayable, user: Contact) => {
  console.log(`user ${user} logout`)
})

4. Event: `message`

Emit when there's a new message.

wechaty.on('message', (this: Sayable, message: Message) => {
  console.log('message ${message} received')
})

5. Event: `error`

Emit when there's an error occurred.

wechaty.on('error', (this: Sayable, err: Error) => {
  console.log('error ${err.message} received')
})

The message here is a Message.

6. Event: `friend`

Fired when we got new friend request, or confirm a friendship.

if request?: FriendRequest is set, then it's a friend request
if request?: FriendRequest is not set, then it's a friend confirmation

wechaty.on('friend', (this: Sayable, 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))
  }
})

7. Event: `room-join`

wechaty.on('room-join', (this: Sayable, room: Room, inviteeList: Contact[], inviter: Contact) => {
  const nameList = inviteeList.map(c => c.name()).join(',')
  console.log(`Room ${room} got new member ${nameList}, invited by ${inviter}`)
})

8. Event: `room-leave`

wechaty.on('room-leave', (this: Sayable, room: Room, leaverList: Contact[]) => {
  const nameList = leaverList.map(c => c.name()).join(',')
  console.log(`Room ${room} lost member ${nameList}`)
})

9. Event: `room-topic`

wechaty.on('room-topic', (this: Sayable, room: Room, topic: string, oldTopic: string, changer: Contact) => {
  console.log(`Room ${room} topic changed from ${oldTopic} to ${topic} by {changer}`)
})

Wechaty Class

Main bot class.

const bot = Wechaty.instance({
  profile
})

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
~~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 stuff with bot here
}

@DEPRECATED Wechaty.self(message: Message): boolean

use Message.self() instead.

Check if message is sent 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!')
}

Wechaty.send(message: Message): Wechaty

send a message

const msg = new Message()
msg.to('filehelper')
msg.content('hello')

wechaty.send(msg)

Message Class

All wechat messages will be encapsulated as a Message.

Message is Sayable

Message.from(contact?: Contact|string): Contact

get the sender from a message, or set it.

1. Message.from(): Contact

get the sender from a message.

2. Message.from(contact: Contact): Contact

set a sender to the message

3. Message.from(contactId: string): Contact

set a sender to the message by it's id

Message.to(contact?: Contact|Room|string): Contact|Room

get the receiver from a message, or set it.

1. Message.to(): Contact|Room

get the destination of the message

2. Message.to(contact: Contact): Contact

set the destination as Contact for the message

3. Message.to(room: Room): Room

set the destination as Room for the message

4. Message.to(contactOrRoomId: string): Contact | Room

set the destination as Room or Contact by id, for the message

Message.room(room?: Room|string): Room

get the room from a message, or set it.

1. Message.room(): Room | null

get the room from Message.

if the message is not in a room, then will return null

2. Message.room(room: Room): Room

set the room for a Message

3. Message.room(roomId: string): Room

set the room by id for a Message

Message.say(content: string): Promise

reply a message to the sender.

Message.ready(): Promise

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(message: Message): boolean

Check if message is sent by self.

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

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

Contact Class

Contact is Sayable

Contact.id: string

Uniq id

Contact.name(): string

Contact.ready(): Promise

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

Contact.say(content: string): Promise

say content to Contact

Class Room

Room is Sayable

Doc is cheap, show you code: Example/Room-Bot

Room.say(content: string, replyTo: Contact|Contact[]): Promise

say content inside Room.

if you set replyTo, then say() will mention them as well.

"@replyTo content"

Room.ready(): Promise

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

Room.refresh(): Promise

force reload data for Room

Room Events

this is Sayable for all listeners.

which means there will be a this.say() the method inside listener call, you can use it sending a message to filehelper, just for logging / reporting / any usage for your convenience

Event: `join`

Room.on('join', (this: Room, inviteeList: Contact[], inviter: Contact) => void)

Event join: Room New Member

room.on('join', function(inviteeList, inviter) {
  const nameList = inviteeList.map(c => c.name()).join(',') 
  console.log(`${nameList} joined the room ${room}, invited by ${inviter}`)
})

Event: `leave`

Room.on('leave', (this, leaverList: Contact[]) => void)

Event: `topic`

Room.on('topic', (topic, oldTopic, changer) => void)

Query Type

type Query = { topic: string|Regex }
Room.find(query : Query) : Room | null
Room.findAll(query : Query) : Room[]

static Room.find(query: Query): Promise<Room|null>

static Room.findAll(query: Query): Promise<Room[]>

static Room.create(contactList: Contact[], topic?: string): Promise

Room.add(contact: Contact): Promise

const friend = message.get('from')
const room = Room.find({ name: 'Group Name' })
if (room) {
  room.add(friend)
}

Room.del(contact: Contact): void

Room.topic(newTopic?: string): string

Room.nick(contact: Contact): string

Room.has(contact Contact): boolean

Room.refresh(): Promise

Room.owner(): Contact|null

Room.member(name: string): Contact|null

Room.memberList(): Contact[]

@deprecated. Room.get(prop): String|Array[{contact: Contact, name: String}]

Get prop from a room.

Supported prop list:

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

room.get('members').length

Class FriendRequest

Send, receive friend request, and friend confirmation events.

When someone sends 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))
  }
})

Doc is cheap, read code: Example/Friend-Bot

FriendRequest.hello: string

verify message

FriendRequest.accept(): void

accept a friend request

FriendRequest.send(contact: Contact, hello: string): void

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

v0.5.0 master (2016/10) The First Typescript Version

Converted to Typescript (2016/10/11) #40
Dockerize Wechaty for easy start #66
Sayablization: Make Wechaty/Contact/Room Sayable, and all this inside wechaty event listeners are Sayable too. #41
BREAKING CHANGE: global event scan listener arguments changed from 1 to 2: now is function(this: Sayable, url: string, code: number) instead of function({url, code}) before.
add test with Node.js v7.0 in CI
add npm run doctor to diagnose wechaty and output useful debug information

v0.4.0 (2016/10/9) The Latest Javascript Version

#32 Extend Room Class with:
Global events: room-join, room-leave, room-topic
Room events: join, leave, topic
Create a new Room: Room.create()
Add/Del/Topic for Room
Other methods like nick/member/has/etc...
#33 New Class FriendRequest with:
Wechaty.on('friend', function(contact: Contact, request: FriendRequest) {}) with Wechaty new Event friend
request.accept() to accept a friend request
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 to WECHATY_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 continuous 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 QR code 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

Everybody is welcome to issue your needs.

Known Issues & Support

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

Contributing

Lint: eslint
```
$ npm run lint
```
Create an issue, fork, then send a pull request(with unit test please).

Wechaty

Connecting ChatBots.

Wechaty had rewritten to Typescript.

Benifits from Typescript

Voice of the Developer

Examples

1. Basic: 6 lines

2. Advanced: dozens of lines

3. Hardcore: hundreds of lines

Deploy

Deploy with Docker

Build

Ship

Deploy with Heroku

Installation

Install from NPM

Install to Cloud9 IDE

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

Setup Xvfb in linux

Wechaty Badge

Markdown

Html

Trouble Shooting

LOG output

NpmLog with Timestamp

DEBUG

Requirement

API Reference

Events

this.say(content: string)

1. Event: scan

2. Event: login

3. Event: logout

4. Event: message

5. Event: error

6. Event: friend

7. Event: room-join

8. Event: room-leave

9. Event: room-topic

Wechaty Class

Wechaty.init(): Wechaty

@DEPRECATED Wechaty.self(message: Message): boolean

Wechaty.send(message: Message): Wechaty

Message Class

Message.from(contact?: Contact|string): Contact

1. Message.from(): Contact

2. Message.from(contact: Contact): Contact

3. Message.from(contactId: string): Contact

Message.to(contact?: Contact|Room|string): Contact|Room

1. Message.to(): Contact|Room

2. Message.to(contact: Contact): Contact

3. Message.to(room: Room): Room

4. Message.to(contactOrRoomId: string): Contact | Room

Message.room(room?: Room|string): Room

1. Message.room(): Room | null

2. Message.room(room: Room): Room

3. Message.room(roomId: string): Room

Message.say(content: string): Promise

Message.ready(): Promise

Message.self(message: Message): boolean

Contact Class

Contact.id: string

Contact.name(): string

Contact.ready(): Promise

Contact.say(content: string): Promise

Class Room

Room.say(content: string, replyTo: Contact|Contact[]): Promise

Room.ready(): Promise

Room.refresh(): Promise

Room Events

Event: join

Event: leave

Setup `Xvfb` in linux

1. Event: `scan`

2. Event: `login`

3. Event: `logout`

4. Event: `message`

5. Event: `error`

6. Event: `friend`

7. Event: `room-join`

8. Event: `room-leave`

9. Event: `room-topic`

Event: `join`

Event: `leave`

Event: `topic`