From ae58319d0ddb80dcdf1664fd682977c9b97d908d Mon Sep 17 00:00:00 2001 From: Souvik Biswas Date: Sun, 1 Aug 2021 13:31:00 +0530 Subject: [PATCH 1/2] Add media file bot --- .../docs/examples/advanced/media-file-bot.md | 3 - .../docs/examples/advanced/media-file-bot.mdx | 383 ++++++++++++++++++ 2 files changed, 383 insertions(+), 3 deletions(-) delete mode 100644 docusaurus/docs/examples/advanced/media-file-bot.md create mode 100644 docusaurus/docs/examples/advanced/media-file-bot.mdx diff --git a/docusaurus/docs/examples/advanced/media-file-bot.md b/docusaurus/docs/examples/advanced/media-file-bot.md deleted file mode 100644 index 77224b47074..00000000000 --- a/docusaurus/docs/examples/advanced/media-file-bot.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Media File Bot ---- \ No newline at end of file diff --git a/docusaurus/docs/examples/advanced/media-file-bot.mdx b/docusaurus/docs/examples/advanced/media-file-bot.mdx new file mode 100644 index 00000000000..3345338cc30 --- /dev/null +++ b/docusaurus/docs/examples/advanced/media-file-bot.mdx @@ -0,0 +1,383 @@ +--- +title: Media File Bot +--- + + +import Tabs from '@theme/Tabs' +import TabItem from '@theme/TabItem' + +import ShortestChatbots from '../../polyglot/transclusions/shortest-chatbots.mdx' + +[![Powered by Wechaty](https://img.shields.io/badge/Powered%20By-Wechaty-brightgreen.svg)](https://github.com/Wechaty/wechaty) +[![JavaScript](https://img.shields.io/badge/%3C%2F%3E-JavaScript-blue.svg)](https://www.javascript.com/) + +Wechaty **Media File Bot** helps in saving media attachments of messages to local files. + +In this tutorial, you will get step-by-step instructions for building the Wechaty Media File Bot from scratch. + +## Try out the bot + +[![Edit wechaty-media-file-bot](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/sbis04/wechaty-media-file-bot/tree/main/?fontsize=14&hidenavigation=1&theme=dark) + +You can try out the Wechaty Media File Bot using this interactive CodeSandbox. + +Just scan the generated QR code with **WeChat** app, and you are ready to play with the bot! + + + +## Requirements + +1. [Node.js](https://nodejs.org/en/download) v12+ +2. [Wechaty](https://github.com/wechaty/wechaty) v0.40+ + +## Getting started + +You should have `Node.js` installed on your system. If you do not have `Node.js` installed (or have a version below 12), then you need to install the latest version of `Node.js` by following the links below: + +:::note Node.js installation docs + +* [Windows](https://nodejs.org/en/download/package-manager/#windows) +* [Linux\(Debian/Ubuntu\)](https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions) +* [macOS](https://nodejs.org/en/download/package-manager/#macos) + +> Installation guide for `Node.js` on other platforms can be found [here](https://nodejs.org/en/download/package-manager/). + +::: + +You can head over to the [Building the bot](#building-the-bot) section to learn how to build the bot on your own. + +Otherwise, if you just want to try out the bot on your local system, follow the steps below: + +### 1. Clone the repository + +Use the following commands to clone the [GitHub repository](https://github.com/wechaty/wechaty-getting-started) and navigate to the directory: + +```bash +git clone https://github.com/wechaty/wechaty-getting-started.git +cd wechaty-getting-started +``` + +### 2. Install dependencies + +You can install the `npm` packages required for running the bot, using this command: + +```sh +npm install +``` + +### 3. Run the bot +You have to `export/set` the environment variables: + + + + + +```bash +export WECHATY_LOG=verbose +export WECHATY_PUPPET=wechaty-puppet-wechat +``` + + + + +```bash +export WECHATY_LOG=verbose +export WECHATY_PUPPET=wechaty-puppet-wechat +``` + + + + +```bash +set WECHATY_LOG=verbose +set WECHATY_PUPPET=wechaty-puppet-wechat +``` + + + + +> There are various **Wechaty puppets** available, you can know more about them [here](https://github.com/wechaty/wechaty-getting-started#working-with-different-puppets). + +Run the bot by using the following command: + +```bash +node examples/advanced/media-file-bot.js +``` + +It will generate a QR code, scan it using **WeChat** or **WhatsApp** (according to the puppet you have used), and you are ready to play with the bot. + +## Building the bot + +Let's get started with building the Wechaty Media File Bot using Wechaty. + +### 1. Initialize project + +Create a new folder called `media-file-bot` and move into that directory: + +```bash +mkdir media-file-bot +cd media-file-bot +``` + +Use the following command to initialize an npm project: + +```bash +npm init -y +``` + +This will generate the `package.json` file containing these: + +```json +{ + "name": "media-file-bot", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "keywords": [], + "author": "", + "license": "ISC" +} +``` + +### 2. Install dependencies + +You will need the `wechaty` NPM package for building this bot & `qrcode-terminal` for displaying the QR code that can be scanned for using the bot. Install them using the following command: + +```sh +npm install wechaty +npm install qrcode-terminal +``` + +You will also need to add dependencies for using any [Wechaty Puppet](https://wechaty.js.org/docs/puppet-providers/) which helps to integrate Wechaty with various **instant messaging (IM) systems** (such as WeChat, WhatsApp, and WeCom): + +1. If you want to use **[WhatsApp](https://www.whatsapp.com/)**, install `wechaty-puppet-whatsapp`: + + ```bash + npm install wechaty-puppet-whatsapp + ``` + +2. If you want to use **[WeChat](https://www.wechat.com/)**, you can try the following puppets: + + * **Web Protocol:** Install `wechaty-puppet-wechat`: + + ```bash + npm install wechaty-puppet-wechat + ``` + + * **iPad Protocol:** + * padlocal: Install `wechaty-puppet-padlocal`: + + ```bash + npm install wechaty-puppet-padlocal + ``` + + Then get a token like `puppet_padlocal_XXX`, know more about puppet service padlocal [here](http://wechaty.js.org/docs/puppet-services/padlocal). + + * paimon: Install `wechaty-puppet-service`: + + ```bash + npm install wechaty-puppet-service + ``` + + Then get a token like `puppet_paimon_XXX`, know more about puppet service paimon [here](http://wechaty.js.org/docs/puppet-services/paimon). + +3. If you want to use **[WeCom](https://work.weixin.qq.com/)**, install `wechaty-puppet-service`: + + ```bash + npm install wechaty-puppet-service + ``` + + Then get a token like `puppet_wxwork_XXXXX`, more about puppet service wxwork [here](https://wechaty.js.org/docs/puppet-services/wxwork/). + +> You can find more information about the puppets [here](https://wechaty.js.org/docs/puppet-providers/). + +### 3. Write code for bot + +Start by creating a new file `media-file-bot.js`. We will be writing the code here. + +Let's import the required packages in the JavaScript file: + +```js +const qrTerm = require("qrcode-terminal"); +const { Wechaty, Message } = require("wechaty"); +``` + +Specify some functions that you will require for handling different events returned by the Wechaty bot. + +* **onScan** + + This function will be used for generating the **QR code** for the puppet specified, and display it on the console. + + ```js + function onScan (qrcode, status) { + qrTerm.generate(qrcode, { small: true }) + } + ``` + +* **onLogin** + + This will print a log message when a user logs in to the bot, and will call the `main()` function. + + ```js + function onLogin (user) { + console.log(`${user} login`) + main() + } + ``` + + We'll look into the content of this `main()` function in a moment. + +* **onLogout** + + This will print a log message when a user logs out of the bot. + + ```js + function onLogout (user) { + console.log(`${user} logout`) + } + ``` + +* **onError** + + This is for printing an error message to the console. + + ```js + function onError (e) { + console.error(e) + } + ``` + +* **onMessage** + + This is for handling the messages and for determining if the messages contain any file attachments. If it contains then save the file locally. + + ```js + async function onMessage(msg) { + console.log(`RECV: ${msg}`); + + if (msg.type() !== Message.Type.Text) { + const file = await msg.toFileBox(); + const name = file.name; + console.log("Save file to: " + name); + file.toFile(name); + } + } + ``` + +You have completed defining all the functions required for handling various bot events. Now, provide a name to initialize the Wechaty bot: + +```js +const bot = new Wechaty({ + name: "media-file-bot", +}); +``` + +Assign proper function to call when an event is triggered by the bot: + +```js +bot.on("scan", onScan); +bot.on("login", onLogin); +bot.on("logout", onLogout); +bot.on("message", onMessage); +bot.on("error", onError); +``` + +Use the following to start the bot: + +```js +bot.start() + .catch(console.error) +``` + +## Running the bot + +In order to run the bot, first you have to **export/set** an environment variable with the type of puppet to use: + + + + + +```bash +export WECHATY_LOG=verbose +export WECHATY_PUPPET=wechaty-puppet-wechat + +# For using WhatsApp: +# export WECHATY_PUPPET=wechaty-puppet-whatsapp + +# For using WeCom: +# export WECHATY_PUPPET=wechaty-puppet-service +# export WECHATY_PUPPET_SERVICE_TOKEN="puppet_wxwork_XXXXX" +``` + + + + +```bash +export WECHATY_LOG=verbose +export WECHATY_PUPPET=wechaty-puppet-wechat + +# For using WhatsApp: +# export WECHATY_PUPPET=wechaty-puppet-whatsapp + +# For using WeCom: +# export WECHATY_PUPPET=wechaty-puppet-service +# export WECHATY_PUPPET_SERVICE_TOKEN="puppet_wxwork_XXXXX" +``` + + + + +```bash +set WECHATY_LOG=verbose +set WECHATY_PUPPET=wechaty-puppet-wechat + +# For using WhatsApp: +# set WECHATY_PUPPET=wechaty-puppet-whatsapp + +# For using WeCom: +# set WECHATY_PUPPET=wechaty-puppet-service +# set WECHATY_PUPPET_SERVICE_TOKEN="puppet_wxwork_XXXXX" +``` + + + + +> If you are using WeCom, you can get token from [puppet service wxwork](http://wechaty.js.org/docs/puppet-services/wxwork). + +Run the bot using the following command: + +```bash +node media-file-bot.js +``` + +This will start the bot and generate a QR code. + +Scan it using your **WeChat/WhatsApp** as per the puppet you have selected, and you are ready to play with the bot! + +## References + +* [Wechaty Getting Started GitHub repository](https://github.com/wechaty/wechaty-getting-started) From 63db38f96219bbb8e3c289efd739e151bb8461f0 Mon Sep 17 00:00:00 2001 From: Souvik Biswas Date: Sun, 1 Aug 2021 13:31:09 +0530 Subject: [PATCH 2/2] Update link in overview --- docusaurus/docs/tutorials/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/tutorials/overview.md b/docusaurus/docs/tutorials/overview.md index d1b004cc0e3..b02bfc373f0 100644 --- a/docusaurus/docs/tutorials/overview.md +++ b/docusaurus/docs/tutorials/overview.md @@ -47,7 +47,7 @@ For better understanding we have classified the bots under three categories taki - [Demo in tutorial](examples/advanced/demo-in-tutorial.md): The demo bot from tutorial - [Busy bot](examples/advanced/busy-bot.mdx): Auto response `busy` message for you when you are busy -- [Media file bot](examples/advanced/media-file-bot.md): Save media attachment in message to local files +- [Media file bot](examples/advanced/media-file-bot.mdx): Save media attachment in message to local files - [Room bot](examples/advanced/room-bot.md): Practical examples illustrating how to do room handling - [Friend bot](examples/advanced/friend-bot.md): Practical example illustrating how to do friend handling - [Gist bot](examples/advanced/gist-bot.md): Best template for bigger modules, with each handler in separated files