diff --git a/docs/.vuepress/public/images/node-sdk/keyboard.png b/docs/.vuepress/public/images/node-sdk/keyboard.png new file mode 100644 index 00000000..a564fd61 Binary files /dev/null and b/docs/.vuepress/public/images/node-sdk/keyboard.png differ diff --git a/docs/develop/nodesdk/config.js b/docs/develop/nodesdk/config.js index 90e9965c..3fd18aab 100644 --- a/docs/develop/nodesdk/config.js +++ b/docs/develop/nodesdk/config.js @@ -25,6 +25,7 @@ module.exports = { { title: '成员对象(Member)', path: 'model/member' }, { title: '频道身份组对象(Role)', path: 'model/role' }, { title: '消息对象(Message)', path: 'model/message' }, + {title: '消息按钮对象(InlineKeyboard)', path: 'model/inline_keyboard'}, { title: '私信对象(DMS)', path: 'model/dms' }, { title: '公告对象(Announce)', path: 'model/announce' }, { title: '精华消息对象(PinsMessage)', path: 'model/pins_message.md' }, @@ -104,6 +105,7 @@ module.exports = { 'message/post_ark_messages', 'message/message_format', 'message/post_reference_messages', + 'message/post_keyboard_message.md', ], }, { diff --git a/docs/develop/nodesdk/message/post_keyboard_message.md b/docs/develop/nodesdk/message/post_keyboard_message.md new file mode 100644 index 00000000..d259b545 --- /dev/null +++ b/docs/develop/nodesdk/message/post_keyboard_message.md @@ -0,0 +1,93 @@ +# 发送带有按钮的消息 + +## 效果 + +![keyboard](../../../.vuepress/public/images/node-sdk/keyboard.png) + +## 功能描述 + +通过在 `MessageToCreate` 中指定 `keyboard` 字段发送带按钮的消息，支持 `keyboard 模版` 和 `自定义 keyboard` 两种请求格式。 + +- 要求操作人在该子频道具有`发送消息`和 对应`消息按钮组件` 的权限。 +- 请求参数 `keyboard 模版` 和 `自定义 keyboard` 只能单一传值。 +- `keyboard 模版` + - 调用前需要先申请消息按钮组件模板，这一步会得到一个模板 id，在请求时填在 `keyboard` 字段上。 + - 申请消息按钮组件模板需要提供响应的 json，具体格式参考 [InlineKeyboard](../model/inline_keyboard.md#InlineKeyboard)。 +- 仅 markdown 消息支持消息按钮。 + +## 使用示例 + +### 1：使用 keyboard 模版 + +```ts +async function demo() { + let { data } = await client.messageApi.postMessage(channelID, { + markdown: { + template_id: 1, + params: [ + { + key: 'title', + value: ['标题'], + }, + ], + }, + msg_id: 'xxxxxx', + keyboard: { + id: '123', + }, + }); +} +``` + +### 2：使用自定义 keyboard + +```ts +async function demo() { + let { data } = await client.messageApi.postMessage(channelID, { + markdown: { + template_id: 1, + params: [ + { + key: 'title', + value: ['标题'], + }, + ], + }, + msg_id: 'xxxxxx', + keyboard: { + content: { + rows: [ + { + buttons: [ + { + id: '1', + render_data: { + label: 'AtBot-按钮1', + visited_label: '点击后按钮1上文字', + }, + action: { + type: 2, + permission: { + type: 2, + specify_role_ids: ['1', '2', '3'], + }, + click_limit: 10, + unsupport_tips: '编辑-兼容文本', + data: '/搜索', + at_bot_show_channel_list: true, + }, + }, + ], + }, + ], + bot_appid: 123123123, + }, + }, + }); +} +``` + + +## 返回说明 + +成功返回 [Message](../model/message.md#message) 对象 diff --git a/docs/develop/nodesdk/model/inline_keyboard.md b/docs/develop/nodesdk/model/inline_keyboard.md new file mode 100644 index 00000000..2fda7932 --- /dev/null +++ b/docs/develop/nodesdk/model/inline_keyboard.md @@ -0,0 +1,70 @@ +# 消息按钮组件（InlineKeyboard） + +### InlineKeyboard + +| 字段名 | 类型 | 描述 | +|-----------|-----------------------------------------------------|---------------------------| +| rows | [InlineKeyboardRow](#inlinekeyboardrow) 消息按钮组件行对象数组 | 数组的一项代表消息按钮组件的一行,最多含有 5 行 | + +### InlineKeyboardRow + +| 字段名 | 类型 | 描述 | +|---------|--------------------------|--------------------------------------------------| +| buttons | [Button](#button) 按钮对象数组 | 数组的一项代表一个按钮，每个 InlineKeyboardRow 最多含有 5 个 Button | + +### Button + +| 字段名 | 类型 | 描述 | +|-------------|------------------------------------|--------------| +| id | string | 按钮 id | +| render_data | [RenderData](#renderdata) 按纽渲染展示对象 | 用于设定按钮的显示效果 | +| action | [Action](#action) 该按纽操作相关字段 | 用于设定按钮点击后的操作 | + +### RenderData + +| 字段名 | 类型 | 描述 | +|---------------|--------|-------------------------------------| +| label | string | 按纽上的文字 | +| visited_label | string | 点击后按纽上文字 | +| style | int | 按钮样式，参考 [RenderStyle](#renderstyle) | + +### RenderStyle + +| 字段名 | 类型 | 描述 | +|-----|-----|------| +| 0 | int | 灰色线框 | +| 1 | int | 蓝色线框 | + +### Action + +| 字段名 | 类型 | 描述 | +| ------------------------ | ------------------------------- | ---------------------------------------------- | +| type | int | 操作类型，参考 [ActionType](#actiontype) | +| permission | [Permission](#permission) 对象 | 用于设定操作按钮所需的权限 | +| click_limit | int | 可点击的次数, 默认不限 | +| data | string | 操作相关数据 | +| at_bot_show_channel_list | bool | false:不弹出子频道选择器 true:弹出子频道选择器 | + +### ActionType +| 值 | 描述 | +| --- | ------------------------------------------------------------------------------------------- | +| 0 | http 或 小程序 客户端识别 schem, data字段为链接 | +| 1 | 回调后台接口, data 传给后台 | +| 2 | at机器人, 根据 at_bot_show_channel_list 决定在当前频道或用户选择频道,自动在输入框 @bot data | + +### Permission + +| 字段名 | 类型 | 描述 | +| ---------------- | ----------- | ------------------------------------------------ | +| type | int | 权限类型，参考 [PermissionType](#permissiontype) | +| specify_role_ids | string 数组 | 有权限的身份组id的列表 | +| specify_user_ids | string 数组 | 有权限的用户id的列表 | + +### PermissionType + +| 值 | 描述 | +| --- | ---------------- | +| 0 | 指定用户可操作 | +| 1 | 仅管理者可操作 | +| 2 | 所有人可操作 | +| 3 | 指定身份组可操作 |