本文内容

自定义机器人使用指南

自定义机器人添加入口

  1. 在群聊中点击右上角的「···」图标,点击群机器人;
  2. 点击添加 webhook 机器人;
  3. 填写机器人名称和简介,即可添加自定义机器人到群聊中。

WOA20211207-142212

(图1:自定义机器人添加入口)

如何使用自定义机器人

  1. 在终端某个群组添加机器人之后,可以获取到 webhook 地址,然后开发者用户按以下说明构造 post data 向这个地址发起 HTTP POST 请求,即可实现给该群组发送消息
  2. webhook 格式是:https://xz.wps.cn/api/v1/webhook/send?key=xxxxxxx
  3. 特别特别要注意:一定要保护好机器人的 webhook 地址,避免泄漏!不要分享到 github、博客等可被公开查阅的地方,否则坏人就可以用你的机器人来发垃圾消息了

相关限制

  1. 消息发送频率限制:每个机器人发送的消息不能超过 20 条/分钟
  2. 消息内容阈值:每条消息不超过 5000 个字符

文本类型

参数说明

参数 是否必填 说明
msgtype 消息类型。text-表示文本类型
text 文本消息
 ∟ content 消息内容

支持通过在消息体 content 中插入<at>标签的方式@人,如果不填写姓名,则服务端将自动填充姓名至@人位置:

  • 使用 id@人:<at user_id="12345">姓名</at>
  • 使用 email@人:<at email="somebody@wps.cn">姓名</at>
  • @所有人:<at user_id="-1">所有人</at>

代码示例

{
   "msgtype":"text",
   "text":{
      "content":"每日数据监控报告:\n今日数据统计结果请相关同事注意<at user_id=\"17856\">李三</at><at user_id=\"-1\">所有人</at>"
   }
}

展示示例

WOA20211207-140051

(图2:文本消息示例)

Markdown 类型

参数说明

参数 是否必填 说明
msgtype 消息类型
markdown markdown 消息
 ∟ text 消息内容

代码示例

{
    "msgtype": "markdown",
    "markdown": {
        "text":"## KAE监控报警\n\n报警内容:网关入口\n\n> 备注:严重程度中等"
    }
}

展示示例

WOA20211207-140209

(图3:Markdown消息示例)

说明:目前只支持 md 语法的子集,具体支持的元素如下(换行可以使用“双空格+\n”或“\n\n”方式),不同语法之间的组合(颜色+标题等)。

名称 语法 说明
@人 使用 id@人:<at user_id="12345">姓名</at>
使用 email@人:<at email="somebody@wps.cn">姓名</at>
@所有人:<at user_id="-1">所有人</at>
/
标题 # 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
/
引用 > 引用内容 /
加粗 **加粗** 如移动端显示有问题可尝试在后面加空格
颜色 <font color='#FF0000'>颜色</font>
<font color='red'>颜色</font>
支持使用十六进制颜色值或对应颜色的英文表示
斜体 *斜体*
_斜体_
/
删除线 ~~删除线~~ /
链接 <链接地址>
[链接名称](链接地址)
/
有序列表 1. 内容 1
2. 内容 2
/
无序列表 - 内容 1
- 内容 2
/
图片 ![](图片地址) /

链接类型

参数说明

参数 是否必填 说明
msgtype 消息类型。link-表示链接类型
title 标题内容
text markdown 格式的消息。换行可以使用“双空格+\n”或“\n\n”方式。
messageUrl 跳转 url
btnTitle 按钮标题,默认为“查看详情”,长度限制 12 个字符

代码示例

{
    "msgtype": "link",
    "link": {
        "title": "日程提醒",
        "text": "需求评审会将于15分钟后开始↵2F-201会议室",
        "messageUrl": "https://kdocs.cn",
        "btnTitle": "查看详情"
    }
}

展示示例

WOA20211207-140255

(图4:链接消息示例)

卡片类型

参数说明

参数 是否必填 说明
msgtype 消息类型。card-表示卡片类型
card 卡片消息,具体内容见搭建卡片消息,备注:目前 webhook 不支持回传型交互组件, 包括回传型按钮、列表选择器、日期选择器、输入框

代码示例

{
    "msgtype":"card",
    "card":{
        "header":{
            "title":{
                "tag":"text",
                "content":{
                    "type":"plainText",
                    "text":"标题"
                }
            },
            "subtitle":{
                "tag":"text",
                "content":{
                    "type":"plainText",
                    "text":"副标题"
                }
            }
        },
        "elements":[
            {
                "tag":"text",
                "content":{
                    "type":"markdown",
                    "text":"普通文本"
                }
            }
        ],
        "i18n":{
            "zh-TW":{
                "header":{
                    "title":{
                        "tag":"text",
                        "content":{
                            "type":"plainText",
                            "text":"標題"
                        }
                    },
                    "subtitle":{
                        "tag":"text",
                        "content":{
                            "type":"plainText",
                            "text":"副標題"
                        }
                    }
                },
                "elements":[
                    {
                        "tag":"text",
                        "content":{
                            "type":"markdown",
                            "text":"普通文本"
                        }
                    }
                ]
            },
            "en-US":{
                "header":{
                    "title":{
                        "tag":"text",
                        "content":{
                            "type":"plainText",
                            "text":"title"
                        }
                    },
                    "subtitle":{
                        "tag":"text",
                        "content":{
                            "type":"plainText",
                            "text":"sub title"
                        }
                    }
                },
                "elements":[
                    {
                        "tag":"text",
                        "content":{
                            "type":"markdown",
                            "text":"common text"
                        }
                    }
                ]
            }
        }
    }
}

展示示例

WOA20231219-155646

(图5:卡片消息示例)

自定义机器人添加 callback

机器人添加 callback

WOA20211207-140336

(图5:机器人添加callback)

callback 可用性校验

创建者在输入框中输入 url,点击保存。服务端会对该地址进行一次 GET 请求,例如:

[GET] https://xz.wps.cn/api/v1/test

第三方收到请求后返回以下 response 数据即可:

{"result":"ok"}

即代表该请求可用。

callback 发送消息

当群聊中用户 at 创建者所配置的 webhook 机器人时,服务端会把该条 at 消息通过 POST 请求发送给第三方,例如:

[POST] https://xz.wps.cn/api/v1/test

请求参数

参数 类型 位置 说明
chatid int64 body 会话 id
creator int64 body 发送者 id
content string body 内容
reply object body 回复内容
robot_key string body 机器人 key
url string body callback 地址创建者所填的 url 地址
ctime int64 body 发送时间
参数 reply 类型 位置 说明
reply_content string body 回复内容
reply_creator int64 body 回复消息发送者 id

请求参数示例

{
    "chatid": 12345,
    "creator": 2324234,
    "content": "@webhook机器人  111",
    "reply": {
        "reply_content": "回复内容",
        "reply_creator": 1234
    },
    "robot_key": "xxx",
    "url": "https://xxxx",
    "ctime": 3452452
}

返回结果示例

{"result":"ok"}

自定义机器人安全设置

如果开发者未保管好 webhook 地址,可能存在地址泄漏后被恶意用来发送垃圾信息的风险,建议开发者至少选择配置一个安全设置。

自定义关键词

设置后,发送的消息需包含至少一个关键词,最多设置 10 个关键词。

示例:设置了关键词:报警、告警后,通过 webhook 机器人发送的消息需带有至少一个关键词,才可以发送成功。

IP 白名单

设置后,只处理来自 IP 白名单地址范围内的请求,最多设置 10 个 IP 地址/地址段,如:192.168.1.1 或 192.168.1.1/24 或 192.168.1.*。

签名校验

设置后,发送请求时需要签名验证来保障信息来源可信。

  • 用户可以在 HTTP Header 中包含签名 (Authorization)。
  • 签名头 (Authorization)验证码计算方法如下:Authorization:" key + ":" + sha1( secret_key + Content-Md5 + Content-Type + DATE)。

注意: HTTP Header 中必须包含以下字段

  • Content-Md5 HTTP Body 中数据的 md5 值十六进制表达方式, 必需小写。
  • Content-Type 目前固定为: application/json。
  • DATE 取当前时间, 格式: Wed, 23 Jan 2013 06:43:08 GMT,签名默认有效时间为 15 分钟。
  • Authorization 上面所说的签名头。

特权用户设置

设置后,只有群主、管理员和 webhook 机器人的添加者,可以编辑或移除此机器人。

WOA20211207-140412

(图6:自定义机器人安全设置)

完整 HTTP 实例

Header

POST https://xz.wps.cn/api/v1/webhook/send
Content-Md5: d41d8cd98f00b204e9800998ecf8427e
Content-Type: application/json
DATE: Wed, 19 Oct 2021 02:16:08 GMT
Authorization:63840ea636369968f9e0de63c0ee02a1:2b9725f94fcf45216edb5392fa540e2083c25b6f

go 示例代码

var calcContentMD5 string
    // 检查Date是否超过15分钟
    dateTime, err := time.Parse(layout, webhookSendRequest.Date)
    if err != nil {
        return robot.ErrWebhookSendByTimestamp

    }
    deltaTime := time.Now().Sub(dateTime)
    if deltaTime < -15*time.Minute || deltaTime > 15*time.Minute {
        return robot.ErrWebhookSendByTimestamp

    }

    // 检查Content-Md5
    contentMD5Array := md5.Sum(webhookSendRequest.Content)
    calcContentMD5 = hex.EncodeToString(contentMD5Array[:])
    if webhookSendRequest.ContentMD5 != calcContentMD5 {
        return robot.ErrWebhookSendBySign
    }

    //获取sign
    splits := strings.Split(webhookSendRequest.Auth, ":")
    if len(splits) != 2 {
        return robot.ErrWebhookSendBySign

    }
    // 计算签名
    str := secretKey + webhookSendRequest.ContentMD5 + webhookSendRequest.ContentType + webhookSendRequest.Date
    sigBytes := sha1.Sum([]byte(str))
    sig := hex.EncodeToString(sigBytes[:])
    if sig != splits[1] {
        return robot.ErrWebhookSendBySign
    }

本文内容