Using Plugin with Wechaty

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

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:N - ManyToManyRoomConnector will broadcast every message in any room to all other rooms.

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.from()?.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.from()?.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.from()?.name() + '(many to many): ' + message.text(),
  whitelist: [ async message => message.type() === Message.Type.Text ],
}
wechaty.use(ManyToManyRoomConnector(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

Hot reloading event handler module files.

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

10 RoomInvitationAccepter

Automatically accepting any room invitations.

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

11 MessageAwaiter

• Description: Wait for a particular message using await syntax (await bot.waitForMessage(...)).
• Author: @ssine

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

wechaty.on('message' async (message) => {
  if (message.text() === 'whatever triggers the dialog') {
    await message.say('hint message')

    // wait for the reply from the same sender
    let reply = await wechaty.waitForMessage({ contact: msg.from()?.id, room: msg.room()?.id })

    // 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

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.

History

• Wechaty Plugin Support with Kickout Example #1939
• Wechaty插件系统发布，让你的机器人快速接入复杂管理和智能对话能力, @rickyyin98, Jul 22, 2020
• 有道智云翻译插件, @chs97, Jul 19, 2020