This is weixin/wechat adapter for hubot.
Branch: master
Clone or download

README.md

weixin Hubot-Weixin

  • hubot hubot version
  • hubot-weixin hubot-weixin version
  • npm npm version
  • nodejs node version
  • 中文版
  • This is wechat/weixin adapter for hubot.
  • Notation: wechat is another name for the popular App weixin in China
  • Goal
    • login once, run anywhere, anytime
    • Make life easier and let bot do something for us in backend

Features of Hubot-WeChat (WeChat Adapter)

  • Basic functions as that in WeChat Web
    • Auto-reply text to group
    • Auto-reply media to group
    • Auto-reply to specific person
  • Auto-report status to maintainer
  • A forever script to launch the hubot instance and mornintoring
  • Aboundants of scripts for hubot
    • integrated with jenkins
    • integrated with turing robot
    • Lots of life information by querying the APIs provided from baidu api-store

Wechat Adapter Configuration

Basic Config

  • The hubot needs a real WeChatID
  • The hubot's WeChatID should be include in the group to be listened on for auto-reply
  • The group/specific person should be save into that contact list

config.yaml

  • A config.yaml is provided to set the configuration items

    • Those items most are for wechat login in Hubot-WeChat startup
  • Get config items method

    • Login the wechat from browser, use the wechatId which is used for hubot
    • Capture data from webwxinit api from browser debug mode
  • url

    • baseUrl -- wx/wx2
    • baseUploadUrl -- file/file2
    • Wechat server has traffic distribution to WX/WX2 server dependent on hubot's WeChat ID
  • Below data are needed and set into config.yaml apporiated fields

    • header
      • cookie
    • BaseRequest
      • Uin
      • Sid
      • Skey
      • DeviceId
  • maintainerName

    • Please fill the maintainer's wechat name (the maintainer should be in hubot's wechat contact list)
    • Hubot will report its online status to maintainer in a configured interval
  • webWxSyncInterval

    • To sync receiving message from WX server
    • Default: 1500 ms
  • syncCheckInterval

    • It is the heartbeat to WX server
    • To trick WX server the login persion still on the web wechat
    • Default: 30s, it is same behavior in web wechat
  • listenOnAllGroups

    • default value: true. Then hubot will listen on all the group where it is in
  • listenGroupNameList

    • It is used to control hubot only listen on some group for auto reply
  • Other config item: it's simple to know from its meaning and you can check the code for its usage

Start Up

by docker

  • docker pull kasperdeng/hubot-weixin
    • size 83M, based on alpine linux
  • Please prepare below config files on host
    • config.yaml with your login info: cookie, Uin, SKey, deviceId
      • For starting in docker, please set logToFile: true and wxLogPath: "/root/hubot/wxhubot.log"
      • e.g. /home/kasper/dockerHubot/config.yaml
    • Your scripts directory
      • e.g. /home/kasper/dockerHubot/scripts
  • start-up command. Please note using -v(volume) to map your config file and log file path on your host.
    • docker run -d -v /home/kasper/dockerHubot/scripts:/root/hubot/scripts -v /home/kasper/dockerHubot/config.yaml:/root/hubot/node_modules/hubot-weixin/config.yaml -v /home/kasper/dockerHubot/wxhubot.log:/root/hubot/wxhubot.log kasperdeng/hubot-weixin
    • Use this command to enter the docker instance for debugging. docker run -it -v /home/kasper/dockerHubot/scripts:/root/hubot/scripts -v /home/kasper/dockerHubot/config.yaml:/root/hubot/node_modules/hubot-weixin/config.yaml -v /home/kasper/dockerHubot/wxhubot.log:/root/hubot/wxhubot.log kasperdeng/hubot-weixin /bin/sh
  • About the image kasperdeng/hubot-weixin, please refer to Dockfile

by npm

  • First, setup hubot(details in Hubot official)
  • add hubot-weixinto hubot's package.json
  • run npm install in your hubot dir
  • start hubot: bin/hubot -a weixin

by git pulling

  • Pull hubot-weixin from here
  • Make symbolic link to your hubot-weixin in Hubot'snode_modules
    • npm link <your hubot-weixin dir>
  • start hubot: bin/hubot -a weixin

Design & Implementation Notes

  • The problem
    • Scanning the QR code to login web wechat
    • No published official WeChat api interface
  • Workaround for login
    • Need login manually by scanning the QR code once
    • Capture all the required data as hubot configuration(details in next slide)
  • Shoot the trouble
    • Use chrome/firefox to analyze web WeChat API
    • Try its web APIs by curl
    • Analyze the parameters and what it is
    • Analyze the wxApp.js
  • Notes:
    • The hubot wechat on the mobile side keeps online is preferred
    • Reason: WeChat server disconnects your hubot with websync failure after 3~4 days. But hubot works again once login mobile wechat app again.

The Adapter Software Hierachy

  • Operations in our Wechat-Hubot

    • wxbot.coffee
  • The coffeescript version's WxChat Web APIs

    • wxApi.coffee
  • The http layer, including sync and async

    • httpclient.coffee

Integrate Adapter to Hubot

  • Implement the needed methods of adapter
    • constructor

      • Getting the hubot robot
    • send

      • hubot sends out message to specific persion/group
    • reply

      • hubot replies message to specific persion/group
    • run

      • New a WxBot
      • Being called in hubot launching It is used to init the wechat groups information
      • Integrate to Hubot by calling
      @emit 'connected'
      
  • Implement a callback to call hubot's receive method to get the incoming message

SDE

  • Getting Started With Hubot on Windows/Unix-Like
  • Backlog management
  • Version control
    • git
  • IDE
    • Sublime
    • or WebStorm/Vim
  • DevEnv
    • Nodejs and npm
    • Use npm install to get all the node modules
      • Inside greatwall, add option --registry=https://registry.npm.taobao.org
  • Programming Language
    • coffeeScript
    • coffeelint to checkstyle

How to write Your Scripts?

  • Please refer to the scirpts in repo
  • Follow the coding style
  • The msg in the scripts provides the http asycn function to get your data from open APIs

Test Your Script

  • With shell adapter
  • Use your WeChat ID to test

Contributor

TODO

  • No much functions to be implemented, most are focus on scripting
  • Unit test

Reference

License

  • See the LICENSE file for license rights and limitations (MIT).