diff --git a/website/docs/advanced-usage/openapp/_category_.json b/website/docs/advanced-usage/openapp/_category_.json new file mode 100644 index 00000000..2e3e5d55 --- /dev/null +++ b/website/docs/advanced-usage/openapp/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Open App", + "position": 20 +} diff --git a/website/docs/advanced-usage/openapp/about.md b/website/docs/advanced-usage/openapp/about.md new file mode 100644 index 00000000..d2e15650 --- /dev/null +++ b/website/docs/advanced-usage/openapp/about.md @@ -0,0 +1,32 @@ +--- +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. +::: + +### 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 diff --git a/website/docs/advanced-usage/openapp/bot.md b/website/docs/advanced-usage/openapp/bot.md new file mode 100644 index 00000000..67ba2b71 --- /dev/null +++ b/website/docs/advanced-usage/openapp/bot.md @@ -0,0 +1,229 @@ +--- +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 { TailchatClient, stripMentionTag } from 'tailchat-client-sdk'; + +const host = ''; +const appId = ''; +const appSecret = ''; + +const client = new TailchatClient(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: , + token: , +} + +Response +{ + data: { + jwt: ".........." + } +} +``` + +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: +``` + +### Call + +Robots can call the interface like ordinary users, such as: + +``` +POST /api/xxx + +Header +Content-Type: application/json +X-Token: + +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: + +Body +{ + "converseId": "", + "groupId": "", + "content": "", + "plain": "", + "meta": {}, +} +``` + +#### Reply message + +``` +POST /api/chat/message/sendMessage + +Header +Content-Type: application/json +X-Token: + +Body +{ + "converseId": "", + "groupId": "", + "content": "", + "plain": "", + "meta": { + mentions: [""], + reply: { + _id: "", + author: "", + content: "", + }, + }, +} +``` + +## Additional Documentation + +- [Tailchat x Laf: Develop a chatbot in 10 minutes](/blog/tailchat-laf-bot) diff --git a/website/docs/advanced-usage/openapp/create.md b/website/docs/advanced-usage/openapp/create.md new file mode 100644 index 00000000..0f59b0a5 --- /dev/null +++ b/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 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/_category_.json b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/_category_.json deleted file mode 100644 index eef3f4d2..00000000 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "进阶使用", - "position": 30 -} diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/assets/github-integration.excalidraw.png b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/assets/github-integration.excalidraw.png deleted file mode 100644 index 8f78dae6..00000000 Binary files a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/assets/github-integration.excalidraw.png and /dev/null differ diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/assets/github-new-app.png b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/assets/github-new-app.png deleted file mode 100644 index e049db81..00000000 Binary files a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/assets/github-new-app.png and /dev/null differ diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/about.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/about.md new file mode 100644 index 00000000..dd292741 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/about.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 1 +title: 关于开放平台 +--- + +开放平台是常见且传统的应用与应用之间进行交互的方式,对于一些简单的需求我们可以通过开放平台来实现应用之间的数据传递。 + +在 Tailchat 中。目前主要提供两种形式的开放平台应用能力: `OAuth` 与 `Bot` + +## 功能介绍 + +### OAuth + +`OAuth` 能够使外部应用能够通过`Tailchat`的账号登录,就像是 `Google`, `Github` 登录方式一样,可以方便用户打造基于 `Tailchat` 的统一用户平台 + +:::info +与 `com.msgbyte.iam` 插件的区别: `iam`插件是提供外部账号登录`Tailchat`的方式,如使用`Github`账号登录`Tailchat`, 而开放平台的OAuth能力则是以`Tailchat`账号登录其他平台。 +::: + +### Bot + +`Bot` 赋予聊天机器人可交互的应用能力,这意味着 Tailchat 不仅仅可以被动接收来自外部的消息,也可以主动将内部聊天的请求转发到外部应用代为处理。 + +[了解更多](./bot) + +## 使用前提 + +在使用开放平台的相关能力前,请确保安装了对应的插件,并确保管理员已经部署与开放了相关的开放平台的能力。 + +作为用户,你需要安装 `com.msgbyte.integration` 插件来将应用加入到自己的群组 + +作为开放平台应用的开发者,你需要额外安装 `com.msgbyte.openapi` 来展示开放平台应用相关所需要的界面 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/bot.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/bot.md new file mode 100644 index 00000000..3d10e87b --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/bot.md @@ -0,0 +1,229 @@ +--- +sidebar_position: 4 +title: 机器人 +--- + +开放平台的机器人是可交互式的机器人解决方案 + +他的主要流程是: + +- 创建openapp +- 获取appid和appsecret +- 进入bot页面,开启bot能力 +- 回调地址填入可以访问到的公网http服务地址 +- 回到群组页面,在群组详情集成功能中输入appid,找到刚刚创建的应用,加入到群组中 +- 在群组中@机器人并输入文本,此时tailchat会向回调地址所示的地址发送一个带消息内容的http请求 +- 在机器人服务中接受到tailchat发送的请求,并通过机器人给对应群组的对应面板发送响应 + +当然,在开始一切工作前请[先在 Tailchat 中创建](./create) + +下面我们来实际操作一下机器人的开发流程: + +## 使用SDK进行开发(Node.js) + +Tailchat 提供了sdk作为快速开发的工具,`tailchat-client-sdk`, 你可以通过以下命令安装 + +```bash +npm install tailchat-client-sdk +``` + +以`koa`为例,我们先创建一个简单的`koa`服务如下: + +创建node项目: + +```bash +mkdir tailchat-bot && cd tailchat-bot +npm init -y +npm install koa koa-router tailchat-client-sdk +``` + +创建`server.js`文件: + +```js +const Koa = require('koa'); +const Router = require('koa-router'); +const app = new Koa(); +const router = new Router(); + +// 定义路由 +router.get('/', async (ctx) => { + ctx.body = 'Hello, World!'; +}); + +router.post('/bot/callback', async (ctx) => { + ctx.body = 'Bot Callback Page'; +}); + +// 注册路由中间件 +app.use(router.routes()); +app.use(router.allowedMethods()); + +// 启动服务 +app.listen(3000, () => { + console.log('Server is running on http://localhost:3000'); +}); +``` + +在此时我们建立了两个基本的路由,`/`与`/bot/callback`, 并监听了`3000`端口, 注意`/bot/callback`监听的是**POST**请求 + +此时我们执行 `node server.js` 可以看到我们的应用会被启动。 + +现在我们要增加一些逻辑,比如我们想要实现一个复读机器人, 那么修改 `/bot/callback` 路由的实现如下: + +```js +import { TailchatClient, stripMentionTag } from 'tailchat-client-sdk'; + +const host = ''; +const appId = ''; +const appSecret = ''; + +const client = new TailchatClient(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'; +}); +``` + +请将 `host` `appId` 和 `appSecret` 分别填入在创建时获取到的 `appId` 和 `appSecret`,`host` 填入 `Tailchat` 服务端的地址, 官方 `nightly` 的地址是 `https://tailchat-nightly.moonrailgun.com` + +至于回复的内容并不重要,只需要确保不要主动返回错误信息即可,Tailchat并不关心返回内容 + +**请注意如果你要把你的代码分享出去的话请保管好你的`appSecret`, 这等价于你的账号的密码** + +逻辑非常简单,从请求中拿到消息的内容, 作者, id, 以及所在的群组id, 会话id。以回复的形式将内容发送出去 + +将该应用部署到线上即可看到效果。 + +:::info +在测试前请确保你已经开启了机器人能力并填入了正确的回调地址 +::: + +## 使用其他语言进行开发 + +既然是网络应用,那么当然不仅仅局限于`nodejs`, 下面是所需要用到的一些网络请求的格式,主要是以开放平台机器人身份向Tailchat服务端发送请求。 + +官方 `nightly` 的api地址是 `https://tailchat-nightly.moonrailgun.com` , 自部署的请替换成自己的后端地址 + +### 登录 + +在所有的请求之前都需要先登录获取jwt token以表明身份,需要发送以下内容: + +``` +POST /api/openapi/bot/login + +Header +Content-Type: application/json + +Body +{ + appId: , + token: , +} + +Response +{ + data: { + jwt: ".........." + } +} +``` + +其中请求体的`token`是一个固定值,需要拼接 `appId` 和 `appSecret` 后以`md5`算法进行加密。最后拿到 `jwt`, `jwt` 要在之后的所有请求中在请求头带上 + +``` +Header +X-Token: +``` + +### 调用 + +机器人可以和普通的用户一样调用接口,如: + +``` +POST /api/xxx + +Header +Content-Type: application/json +X-Token: + +Body +{ + ... +} +``` + +你可以将机器人视为一个普通用户来看待,普通用户所能做的事情机器人都能做,普通用户需要受到的权限限制机器人也会受到。 + +区别在于普通用户是用可视化进行交互的,而机器人是通过api进行交互的。 + +#### 发送信息 + +``` +POST /api/chat/message/sendMessage + +Header +Content-Type: application/json +X-Token: + +Body +{ + "converseId": "", + "groupId": "", + "content": "", + "plain": "", + "meta": {}, +} +``` + +#### 回复信息 + +``` +POST /api/chat/message/sendMessage + +Header +Content-Type: application/json +X-Token: + +Body +{ + "converseId": "", + "groupId": "", + "content": "", + "plain": "", + "meta": { + mentions: [""], + reply: { + _id: "", + author: "", + content: "", + }, + }, +} +``` + +## 其他文档 + +- [Tailchat x Laf: 十分钟开发一个对话机器人](/blog/tailchat-laf-robot) diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/create.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/create.md new file mode 100644 index 00000000..ef90a376 --- /dev/null +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/advanced-usage/openapp/create.md @@ -0,0 +1,14 @@ +--- +sidebar_position: 2 +title: 创建开放平台应用 +--- + +安装 `com.msgbyte.openapi` 插件后可以在左下角设置页面看到多出来一个开放API的功能 + +![](/img/advanced-usage/openapp/1.png) + +填入应用名称与应用描述即可 + +![](/img/advanced-usage/openapp/2.png) + +成功后你可以在你的应用列表中看到你的开放平台应用 diff --git a/website/static/img/advanced-usage/openapp/1.png b/website/static/img/advanced-usage/openapp/1.png new file mode 100644 index 00000000..8634b8f4 Binary files /dev/null and b/website/static/img/advanced-usage/openapp/1.png differ diff --git a/website/static/img/advanced-usage/openapp/2.png b/website/static/img/advanced-usage/openapp/2.png new file mode 100644 index 00000000..44f9129d Binary files /dev/null and b/website/static/img/advanced-usage/openapp/2.png differ