群机器人配置说明

[TOC]

如何使用群机器人

  • 在终端某个群组添加机器人之后,可以获取到webhook地址,然后开发者用户按以下说明构造post data向这个地址发起HTTP POST 请求,即可实现给该群组发送消息。下面举个简单的例子.
    假设webhook是:https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa

特别特别要注意:一定要保护好机器人的webhook地址,避免泄漏!不要分享到github、博客等可被公开查阅的地方,否则坏人就可以用你的机器人来发垃圾消息了。

以下是用curl工具往群组推送文本消息的示例(注意要将url替换成你的机器人webhook地址,content必须是utf8编码):

curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693axxx6-7aoc-4bc4-97a0-0ec2sifa5aaa' \
   -H 'Content-Type: application/json' \
   -d '
   {
        "msgtype": "text",
        "text": {
            "content": "hello world"
        }
   }'
  • 当前自定义机器人支持文本(text)、markdown(markdown)、图片(image)、图文(news)四种消息类型。
  • 机器人的text/markdown类型消息支持在content中使用<@userid>扩展语法来@群成员

消息类型及数据格式

文本类型

{
    "msgtype": "text",
    "text": {
        "content": "广州今日天气:29度,大部分多云,降雨概率:60%",
        "mentioned_list":["wangqing","@all"],
        "mentioned_mobile_list":["13800001111","@all"]
    }
}
参数 是否必填 说明
msgtype 消息类型,此时固定为text
content 文本内容,最长不超过2048个字节,必须是utf8编码
mentioned_list userid的列表,提醒群中的指定成员(@某个成员),@all表示提醒所有人,如果开发者获取不到userid,可以使用mentioned_mobile_list
mentioned_mobile_list 手机号列表,提醒手机号对应的群成员(@某个成员),@all表示提醒所有人

markdown类型

{
    "msgtype": "markdown",
    "markdown": {
        "content": "实时新增用户反馈<font color=\"warning\">132例</font>,请相关同事注意。\n
         >类型:<font color=\"comment\">用户反馈</font>
         >普通用户反馈:<font color=\"comment\">117例</font>
         >VIP用户反馈:<font color=\"comment\">15例</font>"
    }
}
参数 是否必填 说明
msgtype 消息类型,此时固定为markdown
content markdown内容,最长不超过4096个字节,必须是utf8编码

目前支持的markdown语法是如下的子集:

  1. 标题 (支持1至6级标题,注意#与文字中间要有空格)
    # 标题一
    ## 标题二
    ### 标题三
    #### 标题四
    ##### 标题五
    ###### 标题六
    
  2. 加粗
    **bold**
    
  3. 链接
    [这是一个链接](http://work.weixin.qq.com/api/doc)
    
  4. 行内代码段(暂不支持跨行)
    `code`
    
  5. 引用
    > 引用文字
    
  6. 字体颜色(只支持3种内置颜色)
    <font color="info">绿色</font>
    <font color="comment">灰色</font>
    <font color="warning">橙红色</font>
    

图片类型

{
    "msgtype": "image",
    "image": {
        "base64": "DATA",
        "md5": "MD5"
    }
}
参数 是否必填 说明
msgtype 消息类型,此时固定为image
base64 图片内容的base64编码
md5 图片内容(base64编码前)的md5值

注:图片(base64编码前)最大不能超过2M,支持JPG,PNG格式

图文类型

{
    "msgtype": "news",
    "news": {
       "articles" : [
           {
               "title" : "中秋节礼品领取",
               "description" : "今年中秋节公司有豪礼相送",
               "url" : "www.qq.com",
               "picurl" : "http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png"
           }
        ]
    }
}
参数 是否必填 说明
msgtype 消息类型,此时固定为news
articles 图文消息,一个图文消息支持1到8条图文
title 标题,不超过128个字节,超过会自动截断
description 描述,不超过512个字节,超过会自动截断
url 点击后跳转的链接。
picurl 图文消息的图片链接,支持JPG、PNG格式,较好的效果为大图 1068*455,小图150*150。

文件类型

{
    "msgtype": "file",
    "file": {
         "media_id": "3a8asd892asd8asd"
    }
}
参数 是否必填 说明
msgtype 消息类型,此时固定为file
media_id 文件id,通过下文的文件上传接口获取

消息发送频率限制

每个机器人发送的消息不能超过20条/分钟。

文件上传接口

素材上传得到media_id,该media_id仅三天内有效
media_id在同一企业内应用之间可以共享

请求方式:POST(HTTPS
请求地址:https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media?key=KEY&type=TYPE

使用multipart/form-data POST上传文件, 文件标识名为”media”
参数说明:

参数 必须 说明
key 调用接口凭证, 机器人webhookurl中的key参数
type 固定传file

POST的请求包中,form-data中媒体文件标识,应包含有 filename、filelength、content-type等信息

filename标识文件展示的名称。比如,使用该media_id发消息时,展示的文件名由该字段控制

请求示例:

POST https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media?key=693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa&type=file HTTP/1.1
Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
Content-Length: 220

---------------------------acebdf13572468
Content-Disposition: form-data; name="media";filename="wework.txt"; filelength=6
Content-Type: application/octet-stream

mytext
---------------------------acebdf13572468--

返回数据:

{
   "errcode": 0,
   "errmsg": "ok",
   "type": "file",
   "media_id": "1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0",
   "created_at": "1380000000"
}

参数说明:

参数 说明
type 媒体文件类型,分别有图片(image)、语音(voice)、视频(video),普通文件(file)
media_id 媒体文件上传后获取的唯一标识,3天内有效
created_at 媒体文件上传时间戳

上传的文件限制:

  • 要求文件大小在5B~20M之间
© 1998 - 2020 Tencent Inc. All Rights Reserved