Merge branch 'master' into what-can-you-do-with-wechaty

docusaurus/docs/api/wechaty-class.md

@@ -0,0 +1,18 @@
+## Classes
+
+### Wechaty
+
+Wechaty is the main bot class.
+
+A `Bot` is a wechat client that  depends on which  type of puppet is used. The form the Bot takes is widely divided into 3 main categories-
+
+* **web-wechat** - when Puppet-Puppeteer or Puppet-wechat4u is used  
+* **ipad-wechat** - when Puppet-padchat is used
+* **ios-wechat** - when  Puppet-ioscat is used
+
+To understand puppet and its uses do visit the below link-
+
+### [What is a Puppet in Wechaty](https://github.com/wechaty/wechaty-getting-started/wiki/FAQ-EN#31-what-is-a-puppet-in-wechaty)?
+
+> If you want to know how to send message, see Message
+> If you want to know how to get contact, see Contact

docusaurus/docs/howto/overview.mdx

@@ -26,7 +26,7 @@ Wechaty Puppet Service is gRPC for Wechaty Puppet. To use a Wechaty Puppet Servi
 
 ```sh
 export WECHATY_PUPPET=wechaty-puppet-service
-export WECHATY_PUPPET_SERVICE_TOKEN="__TOKEN__"
+export WECHATY_PUPPET_SERVICE_TOKEN="${TOKEN}"
 ```
 
 > You can switch between different Wechaty Puppet Services by changing your TOKEN. The source code works same irrespective of the token you used.

docusaurus/docs/polyglot/dotnet/overview.md

@@ -6,30 +6,41 @@ sidebar_label: .NET
 
 [![.NET Wechaty](https://img.shields.io/badge/Wechaty-.NET-blueviolet)](https://github.com/wechaty/dotnet-wechaty)
 
-- GitHub Repo <https://github.com/wechaty/dotnet-wechaty>
-- Getting Started Template Repo <https://github.com/wechaty/dotnet-wechaty-getting-started>
+.NET Wechaty is the translation of the TypeScript version of Wechaty using .Net Core. As .Net Core supports cross-platform, so .NET Wechaty also supports cross-platform. It has been tested and passed under different operating systems like Windows, Centos, Ubuntu, and has not been tested on the MacOs yet. For more information on .NET Wechaty you can visit the [.NET Wechaty Getting started](https://github.com/wechaty/dotnet-wechaty-getting-started) and to check out the code structure you can visit its [Github repo](https://github.com/wechaty/dotnet-wechaty).
 
 ## Getting Started
 
-Template Repo: <https://github.com/wechaty/dotnet-wechaty-getting-started>
+You can run the below commands for starting the. NET-Wechaty.
 
 ```sh
 git clone [email protected]:wechaty/dotnet-wechaty-getting-started.git
 cd dotnet-wechaty-getting-started
-make install
-make bot
+# install Nuget Package
+nuget restore
+# Set token for your bot open appsettings.json set wechaty configuration
+"WECHATY_PUPPET": "wechaty-puppet-hostie",
+"WECHATY_PUPPET_HOSTIE_TOKEN": "token"
+# Run the bot as
+visual studio  F5 
+# or
+dotnet run
 ```
 
-## Blogs
+## Translation of TypeScript to .NET
 
-Read blogs with the `dotnet` tag at <https://wechaty.js.org/tags.html#dotnet>
+There is a hundred (100) lines class named Image in charge of downloading the WeChat image to different sizes. Below are the links to the Image class for both TypeScript and .NET for a better understanding of the code and the translation.
+
+TypeScript: <https://github.com/wechaty/wechaty/blob/master/src/user/image.ts>
+C#: <https://github.com/wechaty/dotnet-wechaty/blob/master/src/Wechaty/User/Image.cs>
 
 ## History
 
-- [.NET Wechaty如何使用PadLocal Puppet Service, Darren, Jan 28, 2021](https://wechaty.js.org/2021/01/28/csharp-wechaty-for-padlocal-puppet-service/)
-- [.NET Wechaty Getting Start, Darren, Dec 31, 2020](https://wechaty.js.org/2020/12/31/dotnet-wechaty-getting-start/)
+For more information on the. NET-Wechaty releases and history, visit the link below.
+
+* [How .NET Wechaty uses PadLocal Puppet Service, Darren, Jan 28, 2021](https://wechaty.js.org/2021/01/28/csharp-wechaty-for-padlocal-puppet-service/)
+* [.NET Wechaty Getting Start, Darren, Dec 31, 2020](https://wechaty.js.org/2020/12/31/dotnet-wechaty-getting-start/)
 
 ## Maintainers
 
-- [@echofool](https://github.com/echofool)
-- [@jesn](https://wechaty.js.org/contributors/jesn)
+* [@echofool](https://github.com/echofool)
+* [@jesn](https://wechaty.js.org/contributors/jesn)

docusaurus/docs/polyglot/php/overview.md

@@ -6,28 +6,39 @@ sidebar_label: PHP
 
 [![PHP Wechaty](https://img.shields.io/badge/Wechaty-PHP-7de)](https://github.com/wechaty/php-wechaty)
 
-- GitHub Repo <https://github.com/wechaty/php-wechaty>
-- Getting Started Template Repo <https://github.com/wechaty/php-wechaty-getting-started>
+PHP-Wechaty is a PHP programming client derived from the Wechaty ecosystem.PHP is a server scripting language and a powerful tool for making dynamic and interactive Web pages. You can find more information on PHP-Wechaty [here](https://github.com/wechaty/php-wechaty). The [General Architecture Diagram](https://wechaty.js.org/docs/polyglot/diy/) illustrates how the PHP-Wechaty can be implemented on the already existing TypeScript Wechaty ecosystem.
+The World's shortest PHP chatbot is PHP-Wechaty, which can be very easily implemented and used as shown below:
+
+```php
+$wechaty = \IO\Github\Wechaty\Wechaty::getInstance($token, $endPoint);
+$wechaty->onScan(function($qrcode, $status, $data) {
+    $qr = \IO\Github\Wechaty\Util\QrcodeUtils::getQr($qrcode);
+    echo "$qr\n\nOnline Image: https://wechaty.github.io/qrcode/$qrcode\n";
+})->onLogin(function(\IO\Github\Wechaty\User\ContactSelf $user) {
+})->onMessage(function(\IO\Github\Wechaty\User\Message $message) {
+    $message->say("hello from PHP7.4");
+})->start();
+```
 
 ## Getting Started
 
-Template Repo: <https://github.com/wechaty/php-wechaty-getting-started>
+Run the below commands for starting the PHP-Wechaty bot. For further information, also you can visit [Template repo](https://github.com/wechaty/php-wechaty-getting-started).
 
 ```sh
-git clone [email protected]:wechaty/php-wechaty-getting-started.git
-cd php-wechaty-getting-started
+# Install php 7.4+
+sudo yum install php-pecl-grpc
+sudo yum install php-pecl-protobuf
+sudo yum install php-xml
+# curl -sS https://getcomposer.org/installer | php
+php -r "copy('https://install.phpcomposer.com/installer', 'composer-setup.php');"
+php composer-setup.php
+php -r "unlink('composer-setup.php');"
+mv composer.phar /usr/local/bin/composer
 make install
-make bot
+export WECHATY_PUPPET_HOSTIE_TOKEN=your_token_at_here
+make bot # to run the bot
 ```
 
-## Blogs
-
-Read blogs with the `php` tag at <https://wechaty.js.org/tags.html#php>
-
-## History
-
-- [PHP Wechaty, @zhangchunsheng, Aug 5, 2020](https://github.com/wechaty/php-wechaty/)
-
 ## Maintainers
 
-- [@zhangchunsheng](https://github.com/zhangchunsheng)
+* [@zhangchunsheng](https://github.com/zhangchunsheng)

docusaurus/docs/polyglot/python/overview.md

@@ -6,12 +6,22 @@ sidebar_label: Python
 
 [![Python Wechaty](https://img.shields.io/badge/Wechaty-Python-blue)](https://github.com/wechaty/python-wechaty)
 
-- GitHub Repo <https://github.com/wechaty/python-wechaty>
-- Getting Started Template Repo <https://github.com/wechaty/python-wechaty-getting-started>
+Python-wechaty is a Python programming language client derived from the Wechaty ecosystem, allowing developers to connect to various instant messaging software platforms with a small amount of code.Python-wechaty has been committed to improve code robustness, add community out-of-the-box tools, and improve the software development documentation.
+
+## Features of Python-Wechaty
+
+* Send and receive messages.
+* Accept friendship from contact.
+* Create rooms and invites members.
+* Support Wechaty-plugin system.
+* Provides powerful sample code library for robots.
+* Easy to implement.
+
+You can find more information on [Python-Wechaty-getting started](https://github.com/wechaty/python-wechaty-getting-started).The [General Architecture Diagram](https://wechaty.js.org/docs/polyglot/diy/) illustrates on how the Python-Wechaty can be implemented on the existing TypeScript Wechaty ecosystem.
 
 ## Getting Started
 
-Template Repo: <https://github.com/wechaty/python-wechaty-getting-started>
+You can run the below commands for starting the Wechaty-Python.
 
 ```sh
 git clone [email protected]:wechaty/python-wechaty-getting-started.git
@@ -20,18 +30,28 @@ make install
 make bot
 ```
 
+## Translation of TypeScript to Python
+
+As the basic ecosystem of Wechaty is in TypeScript, we only need to translate it to Python. There is a hundred (100) lines of code in class named Image in charge of downloading the WeChat image to different sizes.
+Below are the links to `Image` class for both TypeScript and Python for better understanding of the code and the translation.
+
+* TypeScript: <https://github.com/wechaty/wechaty/blob/master/src/user/image.ts>
+* Python: <https://github.com/wechaty/python-wechaty/blob/master/src/wechaty/user/image.py>
+
 ## History
 
-- [Python Wechaty Beta Released: A Simple Bot, wj-Mcat, Jun 17, 2020](https://wechaty.js.org/2020/06/17/python-wechaty-beta-released/)
+For more information on the Python-Wechaty releases and history, visit the link below.
+
+* [Python Wechaty Beta Released: A Simple Bot, wj-Mcat, Jun 17, 2020](https://wechaty.js.org/2020/06/17/python-wechaty-beta-released/)
 
 ## Blogs
 
-- [教你用python-wecahty和web协议开发机器人, @wj-Mcat, Apr 17, 2021](https://wechaty.js.org/2021/04/17/python-wechaty-use-web/)
-- [Python-wechaty & wechaty-puppet-padlocal的初探, iivveess, Mar 8, 2021](https://wechaty.js.org/2021/03/08/python-wechaty-and-wechaty-puppet-padlocal/)
-- [Python Wechaty如何使用PadLocal Puppet Service, Biofer, Feb, 3, 2021](https://wechaty.js.org/2021/02/03/python-wechaty-for-padlocal-puppet-service/)
+The blogs related to Python-Wechaty are also listed below.
 
-Read more blogs with the `Python` tag at <https://wechaty.js.org/tags.html#python>
+* [教你用python-wecahty和web协议开发机器人, @wj-Mcat, Apr 17, 2021](https://wechaty.js.org/2021/04/17/python-wechaty-use-web/)
+* [Python-wechaty & wechaty-puppet-padlocal的初探, iivveess, Mar 8, 2021](https://wechaty.js.org/2021/03/08/python-wechaty-and-wechaty-puppet-padlocal/)
+* [Python Wechaty如何使用PadLocal Puppet Service, Biofer, Feb, 3, 2021](https://wechaty.js.org/2021/02/03/python-wechaty-for-padlocal-puppet-service/)
 
 ## Maintainers
 
-- [@wj-Mcat](https://wechaty.js.org/contributors/wj-mcat)
+* [@wj-Mcat](https://wechaty.js.org/contributors/wj-mcat)

docusaurus/docs/puppet-providers/official-account.md

@@ -19,6 +19,8 @@ sidebar_label: Official Account
 
 ## Usage
 
+Run wechaty-puppet-official-account :
+
 <!-- MDX import -->
 import Tabs from '@theme/Tabs'
 import TabItem from '@theme/TabItem'
@@ -62,11 +64,126 @@ npm start
 </TabItem>
 </Tabs>
 
-## Roadmap
+## History
 
-- to be added
+Developing a customized WeChat official account is a complex process, which required reading a lot of documents. Developing a robot with a custom reply function based on WeChat official account was a challenge.
 
-## History
+Wechaty-pure-official-account does not encapsulate all the functions in WeChat public account, but extracts the custom customer service dialogue module and encapsulates it as the underlying puppet. In this way, Wechaty was used to develop the customer service dialogue management.
+
+## Quick Start
+
+### Introduction
+
+Using wechaty to develop different platform chatbot is almost no difference at the code level, the underlying puppet has encapsulated all the logic, ‘wechaty’ provides a unified upper interface, so you only need to know how to use wechaty, you can develop powerful multi-platform chatbot.
+
+The development of WeChat Official Account is compared with other platforms, the only difference is that you need to provide WeChat Official Account configuration information, such as’ appId ‘, ‘appSecret’, ‘token’ and so on.
+
+Using wechaty to develop a dialogue chatbot on any platform can be divided into the following three steps:
+
+1. Initialize dialogue platform puppet
+2. Configure puppet to wechaty
+3. Using wechaty upper interface to develop chatbot
+
+In the first step, because the different details of the underlying packages are different, initialization operations are different, such as WeChat official account platform, which requires appId, appSecret and other information separately.
+
+In the second step, when initializing the wechaty instance, it is necessary to configure the puppet as a parameter, so that when wechaty performs dialog operation, it actually calls the underlying logic of the puppet.
+
+In the third step, the upper layer interface of wechaty is used to develop the chatbot. The operation mode is the same for all platforms, so the developer’s attention will be focused on this. The above two steps only need simple configuration.
+
+There are some details about the development of WeChat official account using wechaty. Next we will see how to quickly get the official account chatbot with a few lines of code :
+
+#### Configure Internet address
+
+The official account of WeChat requires the address of the service provider to be external network address, supporting HTTP and HTTPS, and the ports supported respectively are: 80, 443. Therefore, it is very important to have an external IP address in the development phase. Here, we recommend several intranet penetration tools:
+
+- Localtunel : Temporary Internet address can be created, which will be invalid after a certain period of time, but this is in line with the requirements of development stage. The steps are also very simple:
+
+```sh
+npm install -g localtunnel lt –port 80
+```
+
+- [ngrok](https://www.npmjs.com/package/ngrok) : It can create permanent external network addresses, free address numbers and limited bandwidth, but this is enough for WeChats official account development with very small dialogue.
+
+#### Initialization of WeChat official account chatbot
+
+Using wechaty to develop corresponding platform's chatbot, we need to use the corresponding platform puppet, and the WeChat official account corresponds to puppet: `wechaty-puppet-official-account`. The installation tutorial is as follows:
+
+```sh
+npm install wechaty-puppet-official-account
+```
+
+Next is initialization, and WeChat official account requires configuration information such as appId, appSecret, token, etc. The sample code is as follows:
+
+```js
+import { PuppetOA } from 'wechaty-puppet-official-account'
+
+const puppet = new PuppetOA({
+  appId: "wxbd801c28fbe1bbbd",
+  appSecret: "6959408a3ba1c82db1a11d941df65764",
+  token: "token",
+  port: 8080
+})
+```
+
+Next, you need to configure it to wechaty. The example code is as follows:
+
+```js
+const bot = new Wechaty({
+  puppet: puppet
+})
+```
+
+The initialization of wechaty has been completed. The next step is to develop the dialogue logic code of wechaty core.
+
+#### Chatbot Core Logic
+
+In this part, we see the simple message reply function, which is enough to show developers how to develop customized chat robots. The following is the overall sample code:
+
+```js
+import {
+  Contact,
+  Message,
+  Wechaty,
+  log,
+} from 'wechaty'
+import { MessageType } from 'wechaty-puppet'
+
+async function onMessage(msg: Message) {
+  log.info('StarterBot', msg.toString())
+
+  if (msg.text() === 'ding') {
+    await msg.say(`Welcome to wechaty Official Account\n refer to  ： http://www.wechaty.js.org 😄😄😄`)
+  }
+  if (msg.type() == MessageType.Image) {
+    const fileBox = await msg.toFileBox()
+    // send message to talker
+    await msg.say(fileBox)
+  } else {
+    // I am a repeater ~_~~
+    await msg.say(msg.text())
+  }
+}
+
+const bot = new Wechaty({
+  name: 'ding-dong-bot',
+  puppet: new PuppetOA({
+    appId: "wxbd801c28fbe1bbbd",
+    appSecret: "6959408a3ba1c82db1a11d941df65764",
+    token: "token",
+    port: 80
+  })
+})
+
+bot.on('message', onMessage).start()
+  .then(() => log.info('StarterBot', 'Starter Bot Started.'))
+  .catch(e => log.error('StarterBot', e))
+```
+
+## Contributing
+
+Using wechaty to develop WeChat official account chatbot is very simple. It is very friendly to new developers. If you want to see the detailed usage, you can go to [github](https://github.com/wechaty/wechaty-puppet-official-account) Check the latest documentation. You are welcome to mention issues and create PRs.
+
+## Blogs
 
 - [Official-Account Puppet Released, Jing, Nov 6, 2020](https://wechaty.js.org/2020/11/06/wechaty-puppet-oa-released-en/)
 - [Wechaty Workshop for Puppet Makers: How to make a Puppet for Wechaty, Hao, Aug 5, 2020](https://wechaty.js.org/2020/08/05/wechaty-puppet-maker/)