README.md

wechaty-plugin-contrib

Wechaty Plugin Contrib Package for the Community

Image Credit: What is Plugin

Introduction

When you find yourself writing repetitive code, it's time to extract it into a plugin.

Wechaty has a great support for using Plugins by calling Wechaty.use(WechatyPlugin()). A Wechaty Plugin is a JavaScript function that returns a function which accepts a Wechaty instance.

The first Wechaty Plugin system was design by our core team developer @gcaufy from issue #1939(Wechaty Plugin Support with Kick out Example) to PR #1946(feat: added wechaty plugin).

This package is for publishing the Wechaty Plugins that are very common used by the core developer team.

Requirements

1. Wechaty v0.40 or above versions

Plugins Contrib

• Paka Docs

You are welcome to send your plugin to our contrib by creating a Pull Request!

#	Plugin	Author	Feature
1	DingDong	@huan	Reply dong if bot receives a ding message.
2	EventLogger	@huan	Log Wechaty Events for 'scan' | 'login' | 'message' ... etc.
3	QRCodeTerminal	@huan	Show QR Code for Scan in Terminal
4	Heartbeat	@huan	Send emoji periodically
5	ChatOps	@huan	Forward DM & Mention messages to a room
6	RoomConnector	@huan	Connect rooms together with 1:N, M:1, and M:N modes
7	FriendshipAccepter	@huan	Accept friendship automatically, and say/do something for greeting.
8	RoomInviter	@huan	Invite user to rooms by keyword
9	EventHotHandler	@huan	Hot reloading event handler module files
10	RoomInvitationAccepter	@huan	Automatically accepting any room invitations
11	MessageAwaiter	@ssine	Wait for a particular message using await syntax #13

1 DingDong

• Description: Reply dong if bot receives a ding message.
• Author: @huan

import { DingDong } from 'wechaty-plugin-contrib'

const config = {
  mention : true,    // default: true - Response to Mention Self (@/at) Message in Room
  contact : true,    // default: true - Response to Direct Message
  room    : true,    // default: true - Response to Rooms Message
  self    : true,    // default: true - Response to Message that send from the bot itself
}

wechaty.use(DingDong(config))

config as a Function

config can also be a function which receives a message: Message and returns a boolean result to decide whether response a ding message.

Config: (message: Message) => boolean | Promise<boolean>

2 EventLogger

• Description: Log Wechaty Events: "dong" | "message" | "error" | "friendship" | "heartbeat" | "login" | "logout" | "ready" | "reset" | "room-invite" | "room-join" | "room-leave" | "room-topic" | "scan"
• Author: @huan

import { EventLogger } from 'wechaty-plugin-contrib'
const config = ['login', 'ready', 'message']
// Do not provide an config will log all events.
wechaty.use(EventLogger(config))

3 QR Code Terminal

• Description: Show QR Code for Scan in Terminal
• Author: @huan

import { QRCodeTerminal } from 'wechaty-plugin-contrib'
const config = {
  small: false,   // default: false - the size of the printed QR Code in terminal
}
wechaty.use(QRCodeTerminal(config))

4 Heartbeat

• Description: Send emoji periodically
• Author: @huan

import { Heartbeat } from 'wechaty-plugin-contrib'
const config = {
  contact: 'filehelper',    // default: filehelper - Contact id who will receive the emoji
  emoji: {
    heartbeat: '[爱心]',    // default: [爱心] - Heartbeat emoji
  },
  intervalSeconds: 60 * 60, // Default: 1 hour - Send emoji for every 1 hour
}
wechaty.use(Heartbeat(config))

5 ChatOps

• Description: Forward DM & Mention messages to a ChatOps room for logging.
• Author: @huan

import { ChatOps } from 'wechaty-plugin-contrib'

const config = {
  room : 'xxx@chatroom',      // required: room id for ChatOps
  mention?  : true,                // default: true - Response to Mention Self (@/at) Message in Room
  contact?  : true,                // default: true - Response to Direct Message
  whitelist?: ChatOpsFilter,  // whitelist for messages that allow to send to ChatOps Room
  blacklist?: ChatOpsFilter,  // blacklist for messages that forbidden to send to ChatOps Room
}

wechaty.use(ChatOps(config))

6 RoomConnector(s)

Connect rooms together, it supports three modes:

1. 1:N - OneToManyRoomConnector can broadcast the messages in one room to others.
2. M:1 - ManyToOneRoomConnector can summary messages from rooms into one room.
3. M:M - ManyToManyRoomConnector will broadcast every message between rooms.
4. M:N - SourceToTargetRoomConnector will broadcast every message from source room(s) to target room(s).

The difference between SourceToTargetRoomConnector and ManyToManyRoomConnector is that:

1. SourceToTargetRoomConnector have two options to specify:
   1. source: use RoomMatcherOptions to specify the source rooms
   2. target: use RoomFinderOptions to specify the target rooms
2. ManyToManyRoomConnector have one option to specify:
   1. many: use string[] as list of room ids to broadcast to

6.1 OneToManyRoomConnector()

import { OneToManyRoomConnector, OneToManyRoomConnectorConfig } from 'wechaty-plugin-contrib'
const config: OneToManyRoomConnectorConfig = {
  blacklist: [ async () => true ],
  many: [
    '20049383519@chatroom',     // 小句子测试
    '5611663299@chatroom',      // 'ChatOps - Mike BO'
  ],
  map: async message => message.talker().name() + '(one to many): ' + message.text(),
  one: '17237607145@chatroom',  // PreAngel 动态
  whitelist: [ async message => message.type() === Message.Type.Text ],
}
wechaty.use(OneToManyRoomConnector(config))

6.2 ManyToOneRoomConnector()

import { ManyToOneRoomConnector, ManyToOneRoomConnectorConfig } from 'wechaty-plugin-contrib'
const config: ManyToOneRoomConnectorConfig = {
  blacklist: [ async () => true ],
  many: [
    '20049383519@chatroom',     // 小句子测试
    '5611663299@chatroom',      // 'ChatOps - Mike BO'
  ],
  map: async message => message.talker().name() + '(many to one): ' + message.text(),
  one: '17237607145@chatroom',  // PreAngel 动态
  whitelist: [ async message => message.type() === Message.Type.Text ],
}
wechaty.use(ManyToOneRoomConnector(config))

6.3 ManyToManyRoomConnector()

import { ManyToManyRoomConnector, ManyToManyRoomConnectorConfig } from 'wechaty-plugin-contrib'
const config: ManyToManyRoomConnectorConfig = {
  blacklist: [ async () => true ],
  many: [
    '20049383519@chatroom',     // 小句子测试
    '5611663299@chatroom',      // 'ChatOps - Mike BO'
  ],
  map: async message => message.talker().name() + '(many to many): ' + message.text(),
  whitelist: [ async message => message.type() === Message.Type.Text ],
}
wechaty.use(ManyToManyRoomConnector(config))

6.4 SourceToTargetRoomConnector()

import { SourceToTargetRoomConnector, SourceToTargetRoomConnectorConfig } from 'wechaty-plugin-contrib'
const config: SourceToTargetRoomConnectorConfig = {
  blacklist: [ async () => true ],
  source: [
    '5611663299@chatroom',
    /source room topic/i,
  ],
  target: [
    '20049383519@chatroom',
    /target room topic/i,
  ],

  map: async message => message.talker().name() + '(source to target): ' + message.text(),
  whitelist: [ async message => message.type() === Message.Type.Text ],
}
wechaty.use(SourceToTargetRoomConnector(config))

7 FriendshipAccepter

Accept friendship automatically, and say/do something for greeting.

import { FriendshipAccepter, FriendshipAccepterConfig } from 'wechaty-plugin-contrib'
const config: FriendshipAccepterConfig = {
  greeting: 'we are friends now!',
  keyword: '42',
}
wechaty.use(FriendshipAccepter(config))

1. greeting will be sent after the friendship has been accepted.
2. keyword if set, the friendship must match the keyword text.

8 RoomInviter

Invite a contact to the room with password, welcome(public message), and rule(private message) options supported.

import { RoomInviter, RoomInviterConfig } from 'wechaty-plugin-contrib'
const config: RoomInviterConfig = {
  password : 'wechaty',
  room     : '18171595067@chatroom',
  welcome  : 'Welcome to join the room!',
  rule     : 'Please be a good people',
  repeat   : 'You have already in our room',
}
wechaty.use(RoomInviter(config))

9 EventHotHandler DEPRECATED after v0.15

Hot reloading event handler module files.

import { EventHotHandler, EventHotHandlerConfig } from 'wechaty-plugin-contrib'
const config: EventHotHandlerConfig = {
  login: './handlers/on-login',
  logout: './handlers/on0-logout',
}
wechaty.use(EventHotHandler(config))

10 RoomInvitationAccepter

Automatically accepting any room invitations.

import { RoomInvitationAccepter } from 'wechaty-plugin-contrib'
wechaty.use(RoomInvitationAccepter())

11 messagePrompter

• Description: Wait for a particular message using await syntax (await messagePrompter(message)(...)).
• Author: @ssine (refactored by @huan)

import { messageAwaiter } from 'wechaty-plugin-contrib'

wechaty.on('message' async (message) => {
  const prompter = messagePrompter(message)

  const reply = prompter('Hello')
  if (reply) {
    await message.say('hint message')
    // do anything you want...
  }
})

Other arguments include regex which is tested on the message and timeoutSecond which automatically rejects the dialog after specified seconds.

Learn more from:

• New Plugin: Message Awaiter #13
• Refactor the MessageAwaiter plugin #60

Wechaty Plugin Directory

The Wechaty Plugin Contrib will only accept simple plugins which does not dependence very heavy NPM modules, and the SLOC (Source Line Of Code) is no more than 100.

There are many great Wechaty Plugins can not be included in the contrib because they are too powerful. They will be published as a NPM by itself.

We are listing those powerful Wechaty Plugins outside the contrib as in the following list, and you are welcome to add your plugin below if you have published any!

1. VoteOut Plugin by @gcaufy - help you to have a vote and kick out feature for you room.
2. Schedule by @gcaufy - easily schedule jobs for your Wechaty bots.
3. GotKicked by @JesseWeb - monitor whether your bot got kicked out of group chat. Just few line of code to implement this instead fussy judging.
4. WebPanel by @Leo_chen - help you quickly access the web panel
5. Intercom by @huan - helps you to manage your customers/leads/users in the WeChat Room, with the power of the Intercom service.
6. Wechaty Vorpal by @huan - CLI for Chatbot - Extensible Commands for ChatOps, Powered by Vorpal.
7. Freshdesk by @huan - Managing Conversations in WeChat Rooms by Freshdesk.
8. QnAMaker by @huan - Wechaty QnAMaker Plugin helps you to answer questions in WeChat with the power of https://QnAMaker.ai.
9. Weixin OpenAI by @windmemory - Wechaty Weixin OpenAI Plugin helps you to answer questions in WeChat with the power of https://openai.weixin.qq.com.
10. YouDao Translate by @Chs97 - Wechaty YouDao Translate Plugin helps you to translate word in WeChat with the power of https://ai.youdao.com/.
11. Log Monitor by @ArchyWillHe - For log-related DevOps using only WeChat! Fully functional! Very loose coupling! Pretty much pure (other than side effects in I.O.)! Also contains features like QR Rescue (aka 掉线给码) for 2 Wechaties to rescue one another when one is disconnected from the grpc server.
12. Wechaty Xyao by @watertao - Wechaty Xyao Plugin gives bot ability to execute instruction with distributed brain module.
13. Wechaty-fanli by @Leo_chen - help you quickly access the rebate robot about taobao

History

master v1.0

1. Add SourceToTargetRoomConnector to connect a source room to a target room by forward messages to target room.
2. Support ES Modules
   1. Deprecated EventHotHandler due to ESM
3. Change MessageAwaiter plugin to messagePrompter helper function. (#60)

v0.14 master

1. Add types.SayableMessage and types.toSayableMessage
2. Normalize config option:
   1. dm renamed to contact
   2. at renamed to mention

v0.10 (Jun 14, 2020)

1. Export talkers.*, finders.*, and matchers.*
2. Add Mustache template & view support for all talkers.
3. Add mappers.messageMapper()
4. Add matcher.languageMatcher()

v0.8 (Jun 13, 2020)

Add more helper utility functions.

1. Matchers: RoomMatcher, ContactMatcher, MessageMatcher
2. Talkers: RoomTalker, ContactTalker, MessageTalker
3. Finders: RoomFinder, ContactFinder

v0.6 (Jun 9, 2020)

1. New Plugins: OneToManyRoomConnector, ManyToOneRoomConnector, and ManyToManyRoomConnector.
2. New Plugin: FriendshipAccepter for setting to accept friendship automatically.
3. New Plugin: RoomInviter for invite user to rooms with password, rule, and welcome options support.
4. New Plugin: EventHotHandler for hot reloading event handler module files.

v0.4 (May 2020)

1. New plugin: ChatOps: forward all DM & Mention messages to a Room for logging.

v0.2 (May 2020)

Added the following Wechaty Plugins:

1. DingDong
2. EventLogger
3. QRCodeTerminal
4. Heartbeat

v0.0.1 (Apr 2020)

The wechaty-plugin-contrib project was kicked off by the issue Wechaty Plugin Support with Kickout Example #1939 and the PR feat: added wechaty plugin #1946.

Contributors

Maintainers

• @gcaufy - Gcuafy, Creator of WePY
• @huan - Huan LI (李卓桓), Tencent TVP of Chatbot

Copyright & License

• Code & Docs © 2020 Wechaty Contributors https://github.com/wechaty
• Code released under the Apache-2.0 License
• Docs released under Creative Commons