自定义机器人使用指南
自定义机器人添加入口
- 在群聊中点击右上角的「···」图标，点击群机器人；
- 点击添加 webhook 机器人；
- 填写机器人名称和简介，即可添加自定义机器人到群聊中。
（图1：自定义机器人添加入口）
如何使用自定义机器人
- 在终端某个群组添加机器人之后，可以获取到 webhook 地址，然后开发者用户按以下说明构造 post data 向这个地址发起 HTTP POST 请求，即可实现给该群组发送消息
- webhook 格式是：https://xz.wps.cn/api/v1/webhook/send?key=xxxxxxx
- 特别特别要注意：一定要保护好机器人的 webhook 地址，避免泄漏！不要分享到 github、博客等可被公开查阅的地方，否则坏人就可以用你的机器人来发垃圾消息了
相关限制
- 消息发送频率限制：每个机器人发送的消息不能超过 20 条/分钟
- 消息内容阈值：每条消息不超过 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>"
- }
-}
-展示示例
（图2：文本消息示例）
Markdown 类型
参数说明
| 参数 | 是否必填 | 说明 |
|---|---|---|
| msgtype | 是 | 消息类型 |
| markdown | 是 | markdown 消息 |
| ∟ text | 是 | 消息内容 |
代码示例
{
- "msgtype": "markdown",
- "markdown": {
- "text":"## KAE监控报警\n\n报警内容：网关入口\n\n> 备注：严重程度中等"
- }
-}
-展示示例
（图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": "查看详情"
- }
-}
-展示示例
（图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"
- }
- }
- ]
- }
- }
- }
-}
-展示示例
（图5：卡片消息示例）
自定义机器人添加 callback
机器人添加 callback
（图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 机器人的添加者，可以编辑或移除此机器人。
（图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
- }
-