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 Bot Framework for Wechat Personal Account that helps you easy creating bot in 6 lines of javascript, with cross-platform support include Linux, Win32, Darwin(OSX/Mac) and Docker.

:octocat: 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: https://github.com/wechaty/wechaty/issues/40

+ Typescriptilized ...
+ on 12th Oct 2016

VSCode is highly 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 six 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

Working in progress details: Dockerize Wechaty for easy start #66

Wechaty is fully dockerized. So it will be very easy to be used 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

Easy use Wechaty 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:

installed Chrome correctly
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 based on Cloud9(Before Oct 2016, or v0.0.5).

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

The above command will clone wechaty source code to your current directory.

3. Run Demo Bot

cd wechaty
npm install
npm run demo

After a little while, the bot will show you a message of a URL for Login QR Code. You need to scan this QR code in your wechat 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 run unexpected, then 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: https://github.com/npm/npmlog/pull/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 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 send message to filehelper, just for logging/reporting 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 log out, 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`

friend event will be fired when we got a new friend request, or friendship is confirmed.

if request?: FriendRequest is set, then it's a friend request
if request?: FriendRequest is not set, then it's a friendship 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, wechaty will save login status 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
}

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): void

set a sender to the message

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

set a sender to the message by contact id

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

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): void

set the destination as Contact for the message

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

set the destination as Room for the message

4. Message.to(contactOrRoomId: string): void

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

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

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): void

set the room for a Message

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

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

get name from a contact

Contact.remark(): string

get remark name from a contact

Contact.remark(remark: string): Promise

set remark name to a contact

return a Promise, true for modify successful, false for failure.

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 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) {
  console.log(`the room ${room.topic()}, got new members invited by ${inviter.name()}`)
})

Event: `leave`

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

Event: `topic`

Room.on('topic', (this: Room, topic: string, oldTopic: string, changer: Contact) => 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

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

Room.topic(newTopic: string): void

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

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.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 image url of login QR Code(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
Session save/load
Switch to AVA Test Runner
Rewrite to TypeScript
Events
- Use EventEmitter2 to emit message events so that 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

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