原创

企业微信如何使用群机器人?

如何使用群机器人

  • 在终端某个群组添加机器人之后,创建者可以在机器人详情页看的该机器人特有的webhookurl。开发者可以按以下说明a向这个地址发起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编码):
  1. curl 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693axxx6-7aoc-4bc4-97a0-0ec2sifa5aaa' \
  2. -H 'Content-Type: application/json' \
  3. -d '
  4. {
  5. "msgtype": "text",
  6. "text": {
  7. "content": "hello world"
  8. }
  9. }'
  • 当前自定义机器人支持文本(text)、markdown(markdown)、图片(image)、图文(news)四种消息类型。
  • 机器人的text/markdown类型消息支持在content中使用<@userid>扩展语法来@群成员

消息类型及数据格式

文本类型

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

markdown类型

  1. {
  2. "msgtype": "markdown",
  3. "markdown": {
  4. "content": "实时新增用户反馈<font color=\"warning\">132例</font>,请相关同事注意。\n
  5. >类型:<font color=\"comment\">用户反馈</font>
  6. >普通用户反馈:<font color=\"comment\">117例</font>
  7. >VIP用户反馈:<font color=\"comment\">15例</font>"
  8. }
  9. }
参数 是否必填 说明
msgtype 消息类型,此时固定为markdown
content markdown内容,最长不超过4096个字节,必须是utf8编码
目前支持的markdown语法是如下的子集:
  1. 标题 (支持1至6级标题,注意#与文字中间要有空格)
    1. # 标题一
    2. ## 标题二
    3. ### 标题三
    4. #### 标题四
    5. ##### 标题五
    6. ###### 标题六
  2. 加粗
    1. **bold**
  3. 链接
    1. [这是一个链接](http://work.weixin.qq.com/api/doc)
  4. 行内代码段(暂不支持跨行)
    1. `code`
  5. 引用
    1. > 引用文字
  6. 字体颜色(只支持3种内置颜色)
    1. <font color="info">绿色</font>
    2. <font color="comment">灰色</font>
    3. <font color="warning">橙红色</font>

图片类型

  1. {
  2. "msgtype": "image",
  3. "image": {
  4. "base64": "DATA",
  5. "md5": "MD5"
  6. }
  7. }
参数 是否必填 说明
msgtype 消息类型,此时固定为image
base64 图片内容的base64编码
md5 图片内容(base64编码前)的md5值
注:图片(base64编码前)最大不能超过2M,支持JPG,PNG格式

图文类型

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

文件类型

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

模版卡片类型

文本通知模版卡片

  1. {
  2. "msgtype":"template_card",
  3. "template_card":{
  4. "card_type":"text_notice",
  5. "source":{
  6. "icon_url":"https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
  7. "desc":"企业微信",
  8. "desc_color":0
  9. },
  10. "main_title":{
  11. "title":"欢迎使用企业微信",
  12. "desc":"您的好友正在邀请您加入企业微信"
  13. },
  14. "emphasis_content":{
  15. "title":"100",
  16. "desc":"数据含义"
  17. },
  18. "quote_area":{
  19. "type":1,
  20. "url":"https://work.weixin.qq.com/?from=openApi",
  21. "appid":"APPID",
  22. "pagepath":"PAGEPATH",
  23. "title":"引用文本标题",
  24. "quote_text":"Jack:企业微信真的很好用~\nBalian:超级好的一款软件!"
  25. },
  26. "sub_title_text":"下载企业微信还能抢红包!",
  27. "horizontal_content_list":[
  28. {
  29. "keyname":"邀请人",
  30. "value":"张三"
  31. },
  32. {
  33. "keyname":"企微官网",
  34. "value":"点击访问",
  35. "type":1,
  36. "url":"https://work.weixin.qq.com/?from=openApi"
  37. },
  38. {
  39. "keyname":"企微下载",
  40. "value":"企业微信.apk",
  41. "type":2,
  42. "media_id":"MEDIAID"
  43. }
  44. ],
  45. "jump_list":[
  46. {
  47. "type":1,
  48. "url":"https://work.weixin.qq.com/?from=openApi",
  49. "title":"企业微信官网"
  50. },
  51. {
  52. "type":2,
  53. "appid":"APPID",
  54. "pagepath":"PAGEPATH",
  55. "title":"跳转小程序"
  56. }
  57. ],
  58. "card_action":{
  59. "type":1,
  60. "url":"https://work.weixin.qq.com/?from=openApi",
  61. "appid":"APPID",
  62. "pagepath":"PAGEPATH"
  63. }
  64. }
  65. }
请求参数

参数 类型 必须 说明
msgtype String 消息类型,此时的消息类型固定为template_card
template_card Object 具体的模版卡片参数

template_card的参数说明

参数 类型 必须 说明
card_type String 模版卡片的模版类型,文本通知模版卡片的类型为text_notice
source Object 卡片来源样式信息,不需要来源样式可不填写
source.icon_url String 来源图片的url
source.desc String 来源图片的描述,建议不超过13个字
source.desc_color Int 来源文字的颜色,目前支持:0(默认) 灰色,1 黑色,2 红色,3 绿色
main_title Object 模版卡片的主要内容,包括一级标题和标题辅助信息
main_title.title String 一级标题,建议不超过26个字。模版卡片主要内容的一级标题main_title.title和二级普通文本sub_title_text必须有一项填写
main_title.desc String 标题辅助信息,建议不超过30个字
emphasis_content Object 关键数据样式
emphasis_content.title String 关键数据样式的数据内容,建议不超过10个字
emphasis_content.desc String 关键数据样式的数据描述内容,建议不超过15个字
quote_area Object 引用文献样式,建议不与关键数据共用
quote_area.type Int 引用文献样式区域点击事件,0或不填代表没有点击事件,1 代表跳转url,2 代表跳转小程序
quote_area.url String 点击跳转的url,quote_area.type是1时必填
quote_area.appid String 点击跳转的小程序的appid,quote_area.type是2时必填
quote_area.pagepath String 点击跳转的小程序的pagepath,quote_area.type是2时选填
quote_area.title String 引用文献样式的标题
quote_area.quote_text String 引用文献样式的引用文案
sub_title_text String 二级普通文本,建议不超过112个字。模版卡片主要内容的一级标题main_title.title和二级普通文本sub_title_text必须有一项填写
horizontal_content_list Object[] 二级标题+文本列表,该字段可为空数组,但有数据的话需确认对应字段是否必填,列表长度不超过6
horizontal_content_list.type Int 链接类型,0或不填代表是普通文本,1 代表跳转url,2 代表下载附件,3 代表@员工
horizontal_content_list.keyname String 二级标题,建议不超过5个字
horizontal_content_list.value String 二级文本,如果horizontal_content_list.type是2,该字段代表文件名称(要包含文件类型),建议不超过26个字
horizontal_content_list.url String 链接跳转的url,horizontal_content_list.type是1时必填
horizontal_content_list.media_id String 附件的media_id,horizontal_content_list.type是2时必填
horizontal_content_list.userid String 被@的成员的userid,horizontal_content_list.type是3时必填
jump_list Object[] 跳转指引样式的列表,该字段可为空数组,但有数据的话需确认对应字段是否必填,列表长度不超过3
jump_list.type Int 跳转链接类型,0或不填代表不是链接,1 代表跳转url,2 代表跳转小程序
jump_list.title String 跳转链接样式的文案内容,建议不超过13个字
jump_list.url String 跳转链接的url,jump_list.type是1时必填
jump_list.appid String 跳转链接的小程序的appid,jump_list.type是2时必填
jump_list.pagepath String 跳转链接的小程序的pagepath,jump_list.type是2时选填
card_action Object 整体卡片的点击跳转事件,text_notice模版卡片中该字段为必填项
card_action.type Int 卡片跳转类型,1 代表跳转url,2 代表打开小程序。text_notice模版卡片中该字段取值范围为[1,2]
card_action.url String 跳转事件的url,card_action.type是1时必填
card_action.appid String 跳转事件的小程序的appid,card_action.type是2时必填
card_action.pagepath String 跳转事件的小程序的pagepath,card_action.type是2时选填

图文展示模版卡片

  1. {
  2. "msgtype":"template_card",
  3. "template_card":{
  4. "card_type":"news_notice",
  5. "source":{
  6. "icon_url":"https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
  7. "desc":"企业微信",
  8. "desc_color":0
  9. },
  10. "main_title":{
  11. "title":"欢迎使用企业微信",
  12. "desc":"您的好友正在邀请您加入企业微信"
  13. },
  14. "card_image":{
  15. "url":"https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0",
  16. "aspect_ratio":2.25
  17. },
  18. "image_text_area":{
  19. "type":1,
  20. "url":"https://work.weixin.qq.com",
  21. "title":"欢迎使用企业微信",
  22. "desc":"您的好友正在邀请您加入企业微信",
  23. "image_url":"https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0"
  24. },
  25. "quote_area":{
  26. "type":1,
  27. "url":"https://work.weixin.qq.com/?from=openApi",
  28. "appid":"APPID",
  29. "pagepath":"PAGEPATH",
  30. "title":"引用文本标题",
  31. "quote_text":"Jack:企业微信真的很好用~\nBalian:超级好的一款软件!"
  32. },
  33. "vertical_content_list":[
  34. {
  35. "title":"惊喜红包等你来拿",
  36. "desc":"下载企业微信还能抢红包!"
  37. }
  38. ],
  39. "horizontal_content_list":[
  40. {
  41. "keyname":"邀请人",
  42. "value":"张三"
  43. },
  44. {
  45. "keyname":"企微官网",
  46. "value":"点击访问",
  47. "type":1,
  48. "url":"https://work.weixin.qq.com/?from=openApi"
  49. },
  50. {
  51. "keyname":"企微下载",
  52. "value":"企业微信.apk",
  53. "type":2,
  54. "media_id":"MEDIAID"
  55. }
  56. ],
  57. "jump_list":[
  58. {
  59. "type":1,
  60. "url":"https://work.weixin.qq.com/?from=openApi",
  61. "title":"企业微信官网"
  62. },
  63. {
  64. "type":2,
  65. "appid":"APPID",
  66. "pagepath":"PAGEPATH",
  67. "title":"跳转小程序"
  68. }
  69. ],
  70. "card_action":{
  71. "type":1,
  72. "url":"https://work.weixin.qq.com/?from=openApi",
  73. "appid":"APPID",
  74. "pagepath":"PAGEPATH"
  75. }
  76. }
  77. }
请求参数

参数 类型 必须 说明
msgtype String 模版卡片的消息类型为template_card
template_card Object 具体的模版卡片参数

template_card的参数说明

参数 类型 必须 说明
card_type String 模版卡片的模版类型,图文展示模版卡片的类型为news_notice
source Object 卡片来源样式信息,不需要来源样式可不填写
source.icon_url String 来源图片的url
source.desc String 来源图片的描述,建议不超过13个字
source.desc_color Int 来源文字的颜色,目前支持:0(默认) 灰色,1 黑色,2 红色,3 绿色
main_title Object 模版卡片的主要内容,包括一级标题和标题辅助信息
main_title.title String 一级标题,建议不超过26个字
main_title.desc String 标题辅助信息,建议不超过30个字
card_image Object 图片样式
card_image.url String 图片的url
card_image.aspect_ratio Float 图片的宽高比,宽高比要小于2.25,大于1.3,不填该参数默认1.3
image_text_area Object 左图右文样式
image_text_area.type Int 左图右文样式区域点击事件,0或不填代表没有点击事件,1 代表跳转url,2 代表跳转小程序
image_text_area.url String 点击跳转的url,image_text_area.type是1时必填
image_text_area.appid String 点击跳转的小程序的appid,必须是与当前应用关联的小程序,image_text_area.type是2时必填
image_text_area.pagepath String 点击跳转的小程序的pagepath,image_text_area.type是2时选填
image_text_area.title String 左图右文样式的标题
image_text_area.desc String 左图右文样式的描述
image_text_area.image_url String 左图右文样式的图片url
quote_area Object 引用文献样式,建议不与关键数据共用
quote_area.type Int 引用文献样式区域点击事件,0或不填代表没有点击事件,1 代表跳转url,2 代表跳转小程序
quote_area.url String 点击跳转的url,quote_area.type是1时必填
quote_area.appid String 点击跳转的小程序的appid,quote_area.type是2时必填
quote_area.pagepath String 点击跳转的小程序的pagepath,quote_area.type是2时选填
quote_area.title String 引用文献样式的标题
quote_area.quote_text String 引用文献样式的引用文案
vertical_content_list Object[] 卡片二级垂直内容,该字段可为空数组,但有数据的话需确认对应字段是否必填,列表长度不超过4
vertical_content_list.title String 卡片二级标题,建议不超过26个字
vertical_content_list.desc String 二级普通文本,建议不超过112个字
horizontal_content_list Object[] 二级标题+文本列表,该字段可为空数组,但有数据的话需确认对应字段是否必填,列表长度不超过6
horizontal_content_list.type Int 模版卡片的二级标题信息内容支持的类型,1是url,2是文件附件
horizontal_content_list.keyname String 二级标题,建议不超过5个字
horizontal_content_list.value String 二级文本,如果horizontal_content_list.type是2,该字段代表文件名称(要包含文件类型),建议不超过26个字
horizontal_content_list.url String 链接跳转的url,horizontal_content_list.type是1时必填
horizontal_content_list.media_id String 附件的media_id,horizontal_content_list.type是2时必填
jump_list Object[] 跳转指引样式的列表,该字段可为空数组,但有数据的话需确认对应字段是否必填,列表长度不超过3
jump_list.type Int 跳转链接类型,0或不填代表不是链接,1 代表跳转url,2 代表跳转小程序
jump_list.title String 跳转链接样式的文案内容,建议不超过13个字
jump_list.url String 跳转链接的url,jump_list.type是1时必填
jump_list.appid String 跳转链接的小程序的appid,jump_list.type是2时必填
jump_list.pagepath String 跳转链接的小程序的pagepath,jump_list.type是2时选填
card_action Object 整体卡片的点击跳转事件,news_notice模版卡片中该字段为必填项
card_action.type Int 卡片跳转类型,1 代表跳转url,2 代表打开小程序。news_notice模版卡片中该字段取值范围为[1,2]
card_action.url String 跳转事件的url,card_action.type是1时必填
card_action.appid String 跳转事件的小程序的appid,card_action.type是2时必填
card_action.pagepath String 跳转事件的小程序的pagepath,card_action.type是2时选填

消息发送频率限制

每个机器人发送的消息不能超过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发消息时,展示的文件名由该字段控制
请求示例:
  1. POST https://qyapi.weixin.qq.com/cgi-bin/webhook/upload_media?key=693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa&type=file HTTP/1.1
  2. Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468
  3. Content-Length: 220
  4. ---------------------------acebdf13572468
  5. Content-Disposition: form-data; name="media";filename="wework.txt"; filelength=6
  6. Content-Type: application/octet-stream
  7. mytext
  8. ---------------------------acebdf13572468--
返回数据:
  1. {
  2. "errcode": 0,
  3. "errmsg": "ok",
  4. "type": "file",
  5. "media_id": "1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0",
  6. "created_at": "1380000000"
  7. }
参数说明:

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

上传的文件限制:
  • 要求文件大小在5B~20M之间
正文到此结束
Loading...