Skip to main content

Using Plugin with Wechaty

Wechaty Plugin Contrib NPM Version NPM

Wechaty Plugin Contrib Package for the Community

Wechaty Plugin

Image Credit: What is Plugin

Powered by Wechaty TypeScript

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!

#PluginAuthorFeature
1DingDong@huanReply dong if bot receives a ding message.
2EventLogger@huanLog Wechaty Events for 'scan' \| 'login' \| 'message' ... etc.
3QRCodeTerminal@huanShow QR Code for Scan in Terminal
4Heartbeat@huanSend emoji periodically
5ChatOps@huanForward DM & Mention messages to a room
6RoomConnector@huanConnect rooms together with 1:N, M:1, and M:N modes
7FriendshipAccepter@huanAccept friendship automatically, and say/do something for greeting.
8RoomInviter@huanInvite user to rooms by keyword
9EventHotHandler@huanHot reloading event handler module files
10RoomInvitationAccepter@huanAutomatically accepting any room invitations
11MessageAwaiter@ssineWait 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/on0-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!

Wechaty Plugin Contrib

  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#

Last updated on by Souvik Biswas