优化

website/docs/advanced-usage/openapp/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Open App",
+  "position": 20
+}

website/docs/advanced-usage/openapp/about.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 1
+title: About Open App
+---
+
+Open platform is a common and traditional way of interacting between applications. For some simple requirements, we can implement data transfer between applications through an open platform.
+
+In Tailchat. At present, it mainly provides two forms of open platform application capabilities: `OAuth` and `Bot`
+
+## Features
+
+### OAuth
+
+`OAuth` enables external applications to log in through `Tailchat` accounts, just like `Google`, `Github` login methods, which can facilitate users to create a unified user platform based on `Tailchat`
+
+:::info
+The difference from the `com.msgbyte.iam` plugin: `iam` plugin provides a way to log in to `Tailchat` with an external account, such as using a `Github` account to log in to `Tailchat`, while the OAuth capability of the open platform is based on `Tailchat` account to log in to other platforms.
+:::
+
+[Learn more](./oauth)
+
+### Bot
+
+`Bot` endows chatbots with interactive application capabilities, which means that Tailchat can not only passively receive external messages, but also actively forward internal chat requests to external applications for processing.
+
+[Learn more](./bot)
+
+## Prerequisites
+
+Before using the relevant capabilities of the open platform, please ensure that the corresponding plug-in is installed, and ensure that the administrator has deployed the relevant capabilities of the open platform.
+
+As a user, you need to install the `com.msgbyte.integration` plugin to add the application to your group
+
+As a developer of open platform applications, you need to additionally install `com.msgbyte.openapi` to display the interfaces required by open platform applications

website/docs/advanced-usage/openapp/bot.md

@@ -0,0 +1,230 @@
+---
+sidebar_position: 3
+title: Bot
+---
+
+Open platform bot are interactive robot solutions
+
+Main process below:
+
+- Create openapp
+- Get appid and appsecret
+- Enter the bot page and enable the bot ability
+- Fill in the callback address with the public http service address that can be accessed
+- Go back to the group page, enter the appid in the group details integration function, find the app you just created, and add it to the group
+- In the group @bot and enter text, tailchat will send an http request with message content to the address shown in the callback address
+- Receive the request sent by tailchat in the bot service, and send a response to the corresponding panel of the corresponding group through the bot
+
+Of course, [create in Tailchat before you start anything](./create)
+
+Let's take a look at the actual development process of the bot:
+
+## Development with SDK (Node.js)
+
+Tailchat provides sdk as a rapid development tool, `tailchat-client-sdk`, you can install it with the following command
+
+```bash
+npm install tailchat-client-sdk
+```
+
+Taking `koa` as an example, we first create a simple `koa` service as follows:
+
+Create a node project:
+
+```bash
+mkdir tailchat-bot && cd tailchat-bot
+npm init -y
+npm install koa koa-router tailchat-client-sdk
+```
+
+Create `server.js` file:
+
+```js
+const Koa = require('koa');
+const Router = require('koa-router');
+const app = new Koa();
+const router = new Router();
+
+// Define route
+router.get('/', async (ctx) => {
+  ctx.body = 'Hello, World!';
+});
+
+router.post('/bot/callback', async (ctx) => {
+  ctx.body = 'Bot Callback Page';
+});
+
+// Register middleware
+app.use(router.routes());
+app.use(router.allowedMethods());
+
+// Start server
+app.listen(3000, () => {
+  console.log('Server is running on http://localhost:3000');
+});
+```
+
+At this point we have established two basic routes, `/` and `/bot/callback`, and listened to `3000` port, note that `/bot/callback` listens to **POST** requests
+
+At this point we execute `node server.js` to see that our application will be started.
+
+Now we need to add some logic, for example, if we want to implement a repeating bot, then modify the implementation of `/bot/callback` route as follows:
+
+```js
+import { TailchatHTTPClient, stripMentionTag } from 'tailchat-client-sdk';
+
+const host = '<your tailchat instance backend host>';
+const appId = '<appId>';
+const appSecret = '<appSecret>';
+
+const client = new TailchatHTTPClient(host, appId, appSecret)
+
+// ...
+
+router.post('/bot/callback', async (ctx) => {
+  const type = ctx.body.type;
+  
+  if (type === 'message') {
+    const payload = ctx.body.payload;
+    try {
+      const message = await client.replyMessage({
+        messageId: payload.messageId,
+        author: payload.messageAuthor,
+        content: payload.messageSnippet
+      }, {
+        groupId: payload.groupId,
+        converseId: payload.converseId,
+        content: `Your message: ${stripMentionTag(payload.messageSnippet)}`,
+      })
+
+      console.log('send message success:', message)
+    } catch (err) {
+      console.log('send message failed:', err)
+    }
+  }
+  
+  ctx.body = 'Bot Callback Page';
+});
+```
+
+Please fill in `host`, `appId` and `appSecret` into the `appId` and `appSecret` obtained during creation, and `host` into the address of the `Tailchat` server, the official address of `nightly` is `https //tailchat-nightly.moonrailgun.com`
+
+The content of the reply is not important, just make sure not to actively return an error message, Tailchat does not care about the returned content
+
+**Please note that if you want to share your code, please keep your `appSecret`, which is equivalent to your account password**
+
+The logic is very simple. Get the message content, author, id, group id, and converse id from the request. Send content as a reply
+
+Deploy the application online to see the effect.
+
+:::info
+Before testing, please make sure you have enabled the bot ability and filled in the correct callback address
+:::
+
+## Develop in other languages
+
+Since it is a network application, it is of course not limited to `nodejs`. The following are the formats of some network requests that need to be used, mainly sending requests to the Tailchat server as an open platform bot.
+
+The official `nightly` api address is `https://tailchat-nightly.moonrailgun.com`, please replace it with your own backend address for self-deployment
+
+### Login
+
+Before all requests, you need to log in to obtain the jwt token to indicate your identity, and you need to send the following content:
+
+```
+POST /api/openapi/bot/login
+
+Header
+Content-Type: application/json
+
+Body
+{
+  appId: <your app id>,
+  token: <md5(appId+appSecret)>,
+}
+
+Response
+{
+  data: {
+    jwt: "..........",
+    userId: ".........."
+  }
+}
+```
+
+The `token` of the request body is a fixed value, which needs to be encrypted with the `md5` algorithm after splicing `appId` and `appSecret`. Finally get `jwt`, `jwt` must be on the request header in all subsequent requests
+
+```
+Header
+X-Token: <your-jwt>
+```
+
+### Call
+
+Robots can call the interface like ordinary users, such as:
+
+```
+POST /api/xxx
+
+Header
+Content-Type: application/json
+X-Token: <your-jwt>
+
+Body
+{
+  ...
+}
+```
+
+You can treat the bot as an ordinary user. The bot can do everything that ordinary users can do, and the bot will also be subject to the permission restrictions that ordinary users need to be subject to.
+
+The difference is that regular users interact with visualizations, while bots interact with APIs.
+
+#### Send Message
+
+```
+POST /api/chat/message/sendMessage
+
+Header
+Content-Type: application/json
+X-Token: <your-jwt>
+
+Body
+{
+  "converseId": "",
+  "groupId": "",
+  "content": "",
+  "plain": "",
+  "meta": {},
+}
+```
+
+#### Reply message
+
+```
+POST /api/chat/message/sendMessage
+
+Header
+Content-Type: application/json
+X-Token: <your-jwt>
+
+Body
+{
+  "converseId": "<converId/panelId>",
+  "groupId": "<groupId, optional in DM>",
+  "content": "<your message content>",
+  "plain": "<your plained message, optional>",
+  "meta": {
+    mentions: ["<replyMessageAuthorId>"],
+    reply: {
+      _id: "<replyMessageId>",
+      author: "<replyMessageAuthor>",
+      content: "<replyMessageContent>",
+    },
+  },
+}
+```
+
+## Additional Documentation
+
+- [Tailchat x Laf: Develop a chatbot in 10 minutes](/blog/tailchat-laf-robot)

website/docs/advanced-usage/openapp/create.md

@@ -0,0 +1,14 @@
+---
+sidebar_position: 2
+title: Create Open Application
+---
+
+After installing the `com.msgbyte.openapi` plug-in, you can see an additional open API function on the settings page in the lower left corner
+
+![](/img/advanced-usage/openapp/1.png)
+
+Now, fill in the application name and application description
+
+![](/img/advanced-usage/openapp/2.png)
+
+After success, you can see your open platform application in your application list

website/docs/advanced-usage/openapp/oauth.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 5
+title: OAuth
+---
+
+The `Tailchat` open platform supports the `OAuth` login protocol, and you can easily integrate the `Tailchat` account system into your system. Just like our common `Github Login`, `Google Login`, `Apple Login`
+
+Now, you can use `Tailchat` to implement a unified account management system for your multiple platforms.
+
+## Create a new open platform application in Tailchat
+
+You need to create an open platform application and enable **OAuth** service.
+
+Fill in the address that is allowed to be redirected in **callback address**.
+
+![](/img/advanced-usage/openapp/3.png)
+
+## Create a stand-alone application that initiates and accepts callbacks
+
+First of all, we need to have a general understanding of the basic process of **OAuth** before we officially start
+
+![](/img/advanced-usage/openapp/4.png)
+
+Simply put, it is divided into three steps:
+
+- The first step: access authorization, you need to pass client_id: client id, redirect_uri: redirect uri, response_type is code, scope is the scope of authorization, fill in `openid profile` by default, and state is other custom parameters
+- Step 2: After the authorization is passed, it will be redirected to redirect_uri, and the code will be used as its parameter
+- Step 3: After getting the code, you can exchange it for an access token, and then you can directly access resources through the token
+
+You can refer to [https://github.com/msgbyte/tailchat/blob/master/server/test/demo/openapi-client-simple/index.ts](https://github.com/msgbyte/tailchat/blob /master/server/test/demo/openapi-client-simple/index.ts) to implement your own OAuth application
+
+### Main process
+
+Here is a brief overview of the process:
+
+First construct a request address, like:
+```
+<API>/open/auth?client_id=<clientId>&redirect_uri=<redirect_uri>&scope=openid profile&response_type=code&state=123456789
+```
+
+in:
+- `API` is your tailchat backend address, if you use the default deployment scheme, it is your access address.
+- `clientId` is the address of the open platform you applied for in the first step.
+- `redirect_uri` is your callback address, you need to make sure it has been added to the whitelist of allowed callback addresses
+- `scope` is the scope of application authorization, currently fill in `openid profile` fixedly
+- `response_type` is the response type, just fill in `code`
+- `state` and other custom parameters will be called with redirection and `code` parameters.
+
+After the user visits this address, it will jump to the Tailchat platform for login authorization. If the authorization is passed, it will be redirected to the address specified by `redirect_uri`. At this time, the receiving address can get `code` and `state` in the query string.
+
+In the next step, we need to exchange `code` for `token` by sending a POST request. Next, we need to use `token` to obtain user information
+
+```
+POST <API>/open/token
+{
+  "client_id": clientId,
+  "client_secret": clientSecret,
+  "redirect_uri": redirect_uri,
+  "code": code,
+  "grant_type": 'authorization_code',
+}
+```
+
+return value:
+```
+{
+  access_token,
+  expires_in,
+  id_token,
+  scope,
+  token_type
+}
+```
+
+At this point we got the `access_token`, which we can use to request user information:
+
+```
+POST <API>/open/me
+{
+  "access_token": access_token,
+}
+```
+
+return value:
+```
+{
+  sub,
+  nickname,
+  discriminator,
+  avatar,
+}
+```
+
+Among them, `sub` can be understood as the user's id, which is the unique identifier of the user

website/docs/advanced-usage/openapp/ws.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 4
+title: Websocket Bot
+---
+
+In addition to traditional HTTP callback bots, we also support bots based on the websocket long connection protocol.
+
+The long-connection robot can listen to all messages like a normal user, and does not need to be invoke by `@`.
+
+Of course, the disadvantage is that it is not convenient for some platforms that only support http requests, such as `serverless` and other platforms that do not support `websocket`. And currently only the `nodejs` version is implemented.
+
+Here is an example in here:
+
+```ts
+import { TailchatWsClient } from 'tailchat-client-sdk';
+
+const HOST = process.env.HOST;
+const APPID = process.env.APPID;
+const APPSECRET = process.env.APPSECRET;
+
+if (!HOST || !APPID || !APPSECRET) {
+  console.log('require env: HOST, APPID, APPSECRET');
+  process. exit(1);
+}
+
+const client = new TailchatWsClient(HOST, APPID, APPSECRET);
+
+client.connect().then(async() => {
+  console.log('Login Success!');
+
+  client.onMessage((message) => {
+    console.log('Receive message', message);
+  });
+});
+```
+
+Among them, `HOST`, `APPID`, `APPSECRET` represent the server address, the id and secret key of the open platform respectively.
+
+**Please do not upload your secret key on the public platform, the secret key is equivalent to the password**
+
+This operation creates an event listener after connecting to the server, and when any message is received, the content of the message will be printed out.
+
+Similarly, if we need to subscribe the update event of the message, we can use the subscribe message update operation
+
+```ts
+client.onMessageUpdate((message) => {
+  console.log('Receive message', message);
+});
+```