IM公众号开发者文档

1. 基础信息

一、接入指南

基础信息

1、公众号申请地址：http://official.101.com/
2、开发者接口地址：http://official-account.edu.web.sdp.101.com
备注：更多问题咨询请关注“公众号开发者助手”公众号

接口调用说明

开发者可以主动调用第三方开发接口，完成更多功能，具体接口文档详见下文。第三开发接口使用步骤如下：

1.开启开发模式

第三方开发者模式需要先开启第三方开发者模式，获取接口凭证后才能调用。进入公众号网站高级功能 — 开发接口，将模式设为开发模式。

2.获取接口凭证

开发者使用第三方接口前，需要获取接口调用凭证，即APPID和SECRET_KEY，未获取APPID和SECRET_KEY或忘记SECRET_KEY，进入公众号后台管理页面 – 高级功能 - 开发接口页，在开发者模式下，点击重置密码获取。 APPID和SECRET_KEY是用于开发者调用第三方接口的凭据，请妥善保管，若信息泄露请及时重置，每次重置后都会重新生成SECRET_KEY。

3.接口调用请求说明

第三方开发接口请求示例及响应内容使用json格式，每次调用接口时，需要带上接口调用凭证，header设置如下：
Content-Type: application/json
Authorization: APP appid=,token=md5({appid}{secret_key})
例：APPID=3d13c75e2d86d782，SECRET_KEY=4505f7533a81e23750dff69dfdd80dc47e1a76a3，则header设置：
Content-Type: application/json
Authorization: APP appid= 3d13c75e2d86d782,token= 8dfff626cfc978aa8b6a6821073727d9

4.请求数据说明

1、接口请求数据为json格式utf8编码，特殊说明除外。
2、接口返回数据为json格式。

服务器配置说明

开发者若需要接收用户消息，需要配置服务器信息，配置后，用户发送给公众号的消息及菜单点击等事件将推送到开发者配置的服务器URL，配置步骤：

1.填写服务器配置

登录公众号管理后台，在公众号后台管理页面 – 高级功能 - 开发接口页，将模式设为开发者模式（编辑模式使用管理后台定义的自动回复及菜单功能，开发模式下才能使用第三方接口功能，开发模式下网站设置的自动回复和菜单功能将失效，两种模式二选一），填写服务器信息（URL、Token），其中URL是开发者用来接收消息的接口URL（该URL接口需先实现验证代码，验证方法见步骤2）。Token可由开发者可以任意填写，用作生成签名（该Token会和接口URL中包含的Token进行比对，从而验证安全性）。

2.验证服务器地址的有效性

开发者提交信息后，服务器将发送GET请求到填写的服务器地址URL上，GET请求携带四个参数：

参数	描述
signature	加密签名，signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
timestamp	时间戳
nonce	随机数
echostr	随机字符串

开发者通过检验signature对请求进行校验（校验方式如下）。若确认此次GET请求来自服务器，请原样返回echostr参数内容，则接入生效，成为开发者成功，否则接入失败。
校验流程如下：
1.将token、timestamp、nonce三个参数字符串顺序拼接成一个字符串进行sha1加密。
2.开发者获得加密后的字符串可与signature对比，相等则原样返回echostr内容，接入成功，否则接入失败。
php示例代码：

    define("TOKEN", "oa");
    $oaObj = new oaCallbackapiTest();
    $oaObj->valid();
    class oaCallbackapiTest{
        public function valid(){
          $echoStr = $_GET["echostr"];
          if($this->checkSignature()){
            echo $echoStr;exit;
          }else{
            echo 'error';exit;
          }
      }
        private function checkSignature(){
          if (!defined("TOKEN")) {throw new Exception('TOKEN is not defined!');}
          $signature = $_GET["signature"];
          $timestamp = $_GET["timestamp"];
          $nonce = $_GET["nonce"];
            $token = TOKEN;
            $tmpStr = $token.$timestamp.$nonce;
            $tmpStr = sha1( $tmpStr );
            if( $tmpStr == $signature ){
                return true;
            }else{
                return false;
            }
        }
    }

Java示例代码：

    public class TokenServlet extends HttpServlet {
    private static final String TOKEN= "oa";
    public void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        PrintWriter out = response.getWriter();
        String signature = request.getParameter("signature");
        String timestamp = request.getParameter("timestamp");
        String nonce = request.getParameter("nonce");
        String echostr = request.getParameter("echostr");
        String tmpStr = TOKEN + timestamp + nonce;
        tmpStr = DigestUtils.sha1Hex(tmpStr);
        if(tmpStr.equals(signature)){
            out.print(echostr);
        }else{
            out.print("error");
        }
        out.close();
        out = null;
    }
    public void doPost(HttpServletRequest request, HttpServletResponse response)
                throws ServletException, IOException {}
        public void init() throws ServletException {}
        public void destroy() {super.destroy(); }
    }

3.实现业务逻辑

验证服务器地址成功后即接入生效，根据公众号类型（企业号、订阅号）使用对应权限的接口，以满足开发者需求。公众号服务器将会推送消息给开发者配置的URL，消息包括用户发送给公众号的文本消息、语音消息、图片消息及产生的菜单事件消息、订阅事件消息，开发者可以根据收到的消息内容进行消息回复等业务逻辑操作。

开发者规范

开发者在使用第三方接口功能时，需遵守以下规范：

1.用户数据

收集用户数据后，必须保护用户数据安全，防止用户数据泄露，被不法分子利用；不得使用数据对用户给用户造成不良影响，损害用户利益。

2.推送消息

不能发布任何法律、法规和政策禁止的内容。

全局错误返回说明

调用第三方接口错误时，返回错误信息

  {
    "code": "IMP/INVALID_ARGUMENT",
    "message": "无效参数(格式不对,长度过长或过短等)",
    "realm": "im.core.sdp.nd",
    "host_id": "official-account.edu.web.sdp.101.com",
    "request_id": "e340a3d3-3d9f-423f-982f-ff0b5fb4afed",
    "server_time": "2015-11-06T06:31:36.951+0000"
  }

字段	描述
code	用来表示某类的错误，如缺少参数、类型不匹配等等，用来对 http status code 进行扩展，开发人员可以据此进行错误的细节处理。详见错误代码表
message	错误的摘要信息
request_id	错误的uuid
host_id	发生错误的服务器
server_time	发生错误时的服务器时间

错误代码

status code	code	描述
400	IMP/BAD_REQUEST	无效请求
400	IMP/REQUIRE_ARGUMENT	缺少参数
400	IMP/INVALID_ARGUMENT	无效参数(格式不对,长度过长或过短等)
401	IMP/UNAUTHORIZED	未授权(默认)
401	IMP/AUTH_DENIED	授权受限（无权限或IP地址受限等）
403	IMP/ACCESS_DENIED	不允许访问
500	IMP/INTERNAL_SERVER_ERROR	服务器内部错误
404	IMP/OA_NOT_FOUND	公众号未找到
400	IMP/PUBLISH_MENU_FAILURE	发布菜单失败
400	IMP/ADD_TAG_FAILURE	添加分组失败
400	IMP/UPDATE_TAG_FAILURE	修改分组失败
400	IMP/DELETE_TAG_FAILURE	删除分组失败
404	IMP/TAG_NOT_FOUND	分组不存在
400	IMP/USER_TAG_COUNT_OVER_RANGE	分组数不能超过10个
400	IMP/USER_JOIN_TAG_FAILURE	用户加入分组失败
400	IMP/USER_NOT_FOUND	用户不存在或未关注公众号
400	IMP/GROUP_MSG_COUNT_NO_LEFT	剩余群发数目为0
400	IMP/GROUP_NOT_FOUND	群组未找到
400	IMP/GROUP_SEND_FAILURE	群组未找到
400	IMP/GROUP_NOT_FOUND	群消息发送失败
400	IMP/NODE_NOT_FOUND	组织节点未找到
400	IMP/SERVICE_NO_SUB	该用户未关注或已取消关注,无法进行对话
400	IMP/MESSAGE_SEND_FAILURE	发送消息失败
400	IMP/MESSAGE_CONTENT_OVERLENGTH	消息内容不超过4kb
400	IMP/MESSAGE_CONTENT_ERROR	消息内容编码错误
400	IMP/ADD_MATERIAL_FAILURE	添加素材失败
400	IMP/UPDATE_MATERIAL_FAILURE	修改素材失败
400	IMP/DELETE_MATERIAL_FAILURE	删除素材失败
404	IMP/MATERIAL_NOT_FOUND	素材不存在
400	IMP/UPLOAD_AUDIO_FAILURE	上传音频失败
400	IMP/MATERIAL_NOT_FOUND	语音时长太短

版本履历

2015年12月28日

1、新增群发接口，支持p2p消息（发消息给指定两个用户会话），群发消息给指定用户，原群发接口保留，建议使用新接口。

2015年12月12日 v0.3

1、修改“企业号”为“应用号”。

2015年11月18日 v0.2

1、发送消息=》单发消息、群发消息，oaId参数修改为可选，新版可不填写。
2、为保证数据安全，新增编辑模式下不能调用第三方开发接口限制。
3、新增接口数据标准说明。
4、新增版本履历说明。

2015年11月09日 v0.1

1、完善box消息说明：

二、发送消息

单发消息

1.功能说明

开发者通过单发接口可直接推送消息给用户。

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/messages/chat

4.请求数据

  {
    "user_id":123456,
    "login_name":"123456@nd",
    "type":"text",
    "content":"文本消息"
  }

5.参数说明

参数	描述
user_id	用户ID，user_id与login_name二选一
login_name	用户登录名，即工号@org_name或手机号@org_name或用户名@org_name，user_id与login_name二选一
type	消息类别，文本(text)、图片(image)、图文(article)、窗口(box) ，必填
content	发送内容，type=text时为文本内容，换行符\n，大小不超过4k，type=image时为图片素材ID（material_id），type=article时为图文素材ID（material_id），与素材管理接口中语音素材ID对应，type=box时为窗口消息内容（详见box消息规范）,1~2000个字符，必填

6.返回示例

  {
    "message_id":123
  }

7.返回说明

字段	描述
message_id	消息ID

错误返回码code详见全局错误返回说明

群发消息

1.功能说明

开发者也可以通过第三方群发接口，实现更灵活的群发功能。订阅号每天群发数目可通过IM企业后台配置，默认3条，企业号群发数目暂不限制。

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/messages/group

4.请求数据

  {
    "type":"text",
    "content":"文本消息",
    "tag_id":123,
    "node_id":123，
    "gno":"12312"
  }

5.参数说明

参数	描述
type	消息类别，文本(text)、图片(image)、语音（audio）、图文(article)、窗口(box) ，必填
content	发送内容，type=text时为文本内容，换行符\n，大小不超过4k，type=image时为图片素材ID（material_id），type=article时为图文素材ID（material_id），与素材管理接口中语音素材ID对应，type=box时为窗口消息内容（详见box消息规范）,1~2000个字符，必填
tag_id	用户分组ID ，企业号tag_id、node_id和gno三选一，订阅号可选
node_id	组织节点ID，企业号tag_id、node_id和gno三选一，仅限企业号，node_id=0时发送给全部用户
gno	群号，企业号tag_id、node_id和gno三选一，仅限企业号

6.返回示例

  {
    "message_id":123
  }

7.返回说明

字段	描述
message_id	消息ID

错误返回码code详见全局错误返回说明

群发消息【新】

1.功能说明

开发者也可以通过第三方群发接口，实现更灵活的群发功能。订阅号每天群发数目可通过IM企业后台配置，默认3条，企业号群发数目暂不限制。订阅号只能按tag模式发送消息，企业号支持所有模式发送消息

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/messages

4.请求数据

  //node模式(组织节点)：
  {
    "type":"text",
    "content":"文本消息",
    "terms":{
        "name":"node",      //固定
        "args":{
            "node_id":123   //组织节点ID，node_id为0时群发给全部用户
        }
    }
  }
  //tag模式(分组ID)：
  {
    "type":"text",
    "content":"文本消息",
    "terms":{
        "name":"tag",       //固定
        "args":{
            "tag_id":123    //用户分组ID
        }
    }
  }
  //gno模式(群号)：
  {
      "type":"text",
      "content":"文本消息",
      "terms":{
          "name":"gno",     //固定
          "args":{
              "gno":"123"   //群号
          }
      }
  }
  //p2p模式(双人会话)：
  {
    "type":"text",
    "content":"文本消息",
    "terms":{
        "name":"p2p",     //固定
        "args":{
            "p2p_uri":[   //接收消息二人会话的用户ID，最多50对
              ["803404","850917"],
              ["803404","850916"],
              ...
          ]
        }
    }
  }
  //uri模式(用户ID)：
  {
    "type":"text",
    "content":"文本消息",
    "terms":{
        "name":"uri",   //固定
        "args":{
            "uri_list":["803404","850917",...]    //接收消息的用户ID，最多50个
        }
    }
  }

5.参数说明

参数	描述
type	消息类别，文本(text)、图片(image)、语音（audio）、图文(article)、窗口(box) ，必填
content	发送内容，type=text时为文本内容，换行符\n，大小不超过4k，type=image时为图片素材ID（material_id），type=article时为图文素材ID（material_id），与素材管理接口中语音素材ID对应，type=box时为窗口消息内容（详见box消息规范）,1~2000个字符，必填
terms	群发条件参数，必填
name	群发消息条件类型，node（按组织节点群发）、tag（按分组群发）、gno（按群号群发）、p2p（按双方会话群发即发送消息至二人对话）、uri（按用户ID群发）
tag_id	用户分组ID，订阅号或应用号，name=tag时必填
node_id	组织节点ID，仅限应用号，name=node时必填，node_id=0时发送给全部用户
gno	群号，仅限应用号，name=gno时必填
p2p_uri	接收消息二人会话的用户ID，最多50对，仅限应用号，name=p2p时必填
uri	接收消息的用户ID，最多50个，仅限应用号，name=uri时必填

6.返回示例

  {
    "message_id":123
  }

7.返回说明

字段	描述
message_id	消息ID

错误返回码code详见全局错误返回说明

box消息规范

1、示例

  <box data-summary="等级提升通知" >
    <div class="row">
      <div class="col-6">
        <span>恭喜您，等级提升到</span><span style="color: #c67796;">5级</span>
      </div>
    </div>
  </box>
  注意：box消息严格遵守xml规范，box中的文本，如特殊字符（空格，>, < 等），请确保按照xml标准进行转义

2、说明

字段	描述
box	窗口消息的根标签
box[data-summary]	窗口消息的摘要描述文本，客户端会将它显示在最近聊天窗口的会话内容中
box[data-replaceid]	data-replaceid="代理标识_代理自定义id",作为box消息消息替换的唯一标识；消息支持覆盖替换，如果data-replaceid与旧的box消息相同，客户端则进行消息覆盖处理，否则作为新消息展示
box.div	窗口消息的栅格化布局，参考“栅格化布局规范”

3、栅格化布局规范

栅格化布局用于通过一系列的行（row）与列（column）的组合来排列消息体内容，你的内容就可以放入这些创建好的布局中。
消息体定义中，可以使用box识别的几种标签(文本、图片、按钮)，按照每一行，放入多少列的标签来进行布局，客户端会根据box中排列最多的列数来算出一个消息展示在聊天窗的真正宽度。
目前box消息体支持6列，每一列的宽度，根据手机屏幕展示消息最大宽度除以6来计算，因此，每一列的宽度是相对宽度

  <div class="row">
    <div class="col-1"><span>.col-1</span></div>
    <div class="col-1"><span>.col-1</span></div>
    <div class="col-1"><span>.col-1</span></div>
    <div class="col-1"><span>.col-1</span></div>
    <div class="col-1"><span>.col-1</span></div>
    <div class="col-1"><span>.col-1</span></div>
  </div>
  <div class="row">
    <div class="col-4" style="text-align:center"><span>.col-2</span></div>
    <div class="col-2"style="text-align:left"><span>.col-4</span></div>
  </div>
  <div class="row">
    <div class="col-3" style="text-align:right"><span>.col-3</span></div>
    <div class="col-3"><span>.col-3</span></div>
  </div>
  <div class="row">
    <div class="col-2"><span>.col-2</span></div>
    <div class="col-2"><span>.col-2</span></div>
    <div class="col-2"><span>.col-2</span></div>
  </div>
  <div class="row">
    <div class="col-6"><span>.col-6</span></div>
  </div>

说明：
div.row：表示一行布局
div.col-1: 表示一行布局中的 1 列，占用整行布局的 1/6
div.col-2: 表示一行布局中的 2 列，占用整行布局的 2/6
div.col-3: 表示一行布局中的 3 列，占用整行布局的 3/6
div.col-4: 表示一行布局中的 4 列，占用整行布局的 4/6
div.col-6: 表示一行布局中的 6 列，占满整行布局
col 支持对齐：左对齐（text-align：left），默认对齐格式、右对齐（text-align：right）、居中对齐（text-align：center）

4、文本标签规范

  <span>这是一段文本消息</span>
  <span>这是一段</span><span style="color:#FFFFFF">包含红色文本<span><span>消息</span>。
  <span>这是一段</span><span style="text-decoration:underline">下划线文本<span><span>消息</span>。
  <span>这是一段</span><span style="font-weight:bold">加粗文本</span><span>消息</span>。
  <span>这是一段</span><span style="font-size:1.2em">特定字体大小文本</span><span>消息</span>。

说明：
span[style=""] 表示文本的样式，目前支持color, text-decoration,font-weight,font-size 样式
span[style="font-size:1.2em"] 考虑到手机上不同屏幕分辨率，font-size 只支持em属性，即在手机默认字体大小上的放大倍数

5、按钮标签规范

  <button class="link-default" data-href="cmp://com.nd.weibo/home_page/?uid=1223" style="color: red;">
    默认链接
  </button>
  <button class="btn-default" data-href="cmp://com.nd.weibo/home_page/?uid=1223" disabled="disabled">
    默认按钮
  </button>
  <button class="arrow-default" data-href="cmp://com.nd.weibo/home_page/?uid=1223">
    箭头文字
  </button>

说明：
button[class="btn-default"]: 按钮样式
button[class="arrow-defult"]: 按钮箭头，默认向右箭头样式；
button[class="link-default"]: 链接样式
button[data-href="url"]: 页面/事件跳转地址；
button[style="..."]: 按钮/链接样式；
button[disabled="disabled"]: 设置按钮/链接不可点击并置灰；不填表示可点击

6、图片标签规范

  <img src="dentry://12392138091230921" class="img-square" mime="jpeg" width="240px" height="320px"
      size="1201024" alt="图片说明"/>

说明：
img[class=image-square]：图片显示为正方形，如果是矩形原图会做裁剪
img[class=image-default]：图片显示为正常高宽比例的缩略图
img[src]: 图片的内容来源，protocol:// + 内容的形式：
　　内容服务：img[src]= "dentry://12392138091230921"，dentry值为图片素材中source_id
　　用户头像：img[src] = "user://3489348",user值为用户ID
　　HTTP图片：img[src] = "https://www.baidu.com/img/bdlogo.png"

三、接收消息

接收消息

当用户向公众号发送消息时，公众号服务器将发送POST请求开发者配置的URL，发送消息数据，消息数据格式如下：

1.文本消息

  {
    "oa_id":100,
    "user_id":123456,
    "type":"text",
    "content":"文本消息"
  }

字段	描述
oa_id	公众号编号
user_id	用户ID
type	消息类型，文本消息为text
content	文本消息内容

2.图片消息

  {
    "oa_id":100,
    "user_id":123456,
    "type":"image",
    "content":{
      "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
      "mime":"jpeg",
      "width":240,
      "height":320,
      "size":1024,
      "title":"图片标题",
      "md5":"827ccb0eea8a706c4c34a16891f84e7b"
    }
  }

字段	描述
oa_id	公众号编号
user_id	用户ID
type	消息类型，图片消息为image
source_id	内容服务目录项ID（文件资源ID），获取详见内容服务说明
mime	图片格式（参考HTTP mime定义）
width	图片宽度(pixel)
height	图片高度(pixel)
size	图片大小(byte)
title	图片标题，长度不超过64个字符
md5	文件md5

3.语音消息

  {
    "oa_id":100,
    "user_id":123456,
    "type":"audio",
    "content":{
      "title":"标题",
      "src":"96340084-775d-4740-ae3f-b2dea289618b ",
      "mime":"amr",
      "dura":12,
      "size":3076,
      "md5":"bcb31b38e4c01691881e38023dea69e9"
    }
  }

字段	描述
oa_id	公众号编号
user_id	用户ID
type	消息类型，语音消息为audio
title	语音标题，1~20个字符
src	内容服务目录项ID（文件资源ID），获取详见内容服务说明
mime	音频格式（参考HTTP mime定义）
dura	音频持续时长（ms）
size	音频文件大小(byte)
md5	文件MD5

4.事件消息

  {
    "oa_id":100,
    "user_id":123456,
    "type":"event",
    "content":{
      "name":"click",
      "key":"V_1001_SUB_BUTTON"
    }
  }

字段	描述
oa_id	公众号编号
user_id	用户ID
type	消息类型，事件消息为event
name	事件类型，菜单点击事件为click，关注订阅号事件为oa_subscribe，收藏应用号事件为oa_collect
key	事件代码，type为click时与自定义菜单接口中KEY值对应，type为oa_subscribe或oa_collect时无key值

回复消息

当开发者收到用户向公众号发送的消息时，可以根据消息结构（详见“二、接收消息”）进行响应，公众号根据响应的数据回复给用户，回复类型支持文本、图片、图文、语音、窗口消息等。
如果开发者服务器无法及时回复消息，必须做出响应，如直接回复success，避免公众号服务器对此作其他处理或重试，响应后可以异步调用消息接口（祥见消息接口说明）发送消息给用户。

回复消息数据格式如下：

  {
    "oa_id":100,
    "user_id":123456,
    "msg":{
      "type":"text",
      "content":"文本消息"
    }
  }

参数	描述
oa_id	公众号编号
user_id	用户ID
type	消息类别，文本(text)、图片(image)、语音（audio）、图文(article)、窗口(box) ，必填
content	回复消息内容，type=text时为文本内容，大小不超过4k，type=image时为图片素材ID（material_id），type=article时为图文素材ID（material_id），与素材管理接口中语音素材ID对应，type=box时为窗口消息内容（详见box消息规范）,1~2000个字符，必填

四、素材管理

添加素材

添加图片/语音：

1.功能说明

上传图片/语音并添加到公众号素材库。

2.请求方式

http请求方式：POST

3.请求地址

添加图片：http://official-account.edu.web.sdp.101.com/app/materials/images
添加语音：http://official-account.edu.web.sdp.101.com/app/materials/audios

4.请求数据

  Content-Type: multipart/form-data; boundary=---------------------------bcff34665164
  Content-Length: {请求数据长度}
  -----------------------------bcff34665164
  Content-Disposition: form-data; name="title"

  {图片/语音标题}
  -----------------------------bcff34665164
  Content-Disposition: form-data; name="file"; filename="{文件名.扩展名}"
  Content-Type: {文件mime}

  {文件块数据}
  -----------------------------bcff34665164

5.参数说明

字段	描述
file	图片/语音文件数据，图片支持bmp/png/jpeg/jpg/gif格式，图片大小不超过2M，语音支持mp3/wav/amr格式，语音大小不超过5M
title	图片/语音标题，长度不超过64个字符，必填

6.返回示例

  {
    "material_id":123
  }

7.返回说明

字段	描述
material_id	素材ID

添加图文：

1.功能说明

添加图文素材到素材库，图文封面图片参数需先调用添加图片接口，根据图片素材接口返回的素材ID获取。

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/materials/articles

4.请求数据

  {
    "type":"article",
    "content": [
      {
        "author":"作者",
        "title":"标题",
        "cover": {
          "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
          "mime":"jpeg",
          "width":240,
          "height":320,
          "size":1201024,
          "title":"图片标题",
          "md5":"1146ccc9a0e484f59ff14f8b654f81e1"
        },
        "summary":"xxx",
        "content":"图文正文内容",
        "from_url":"http://www.baidu.com"
      },
      ... //单图文一个，多图文多个，最多不超过8个
    ]
  }

5.参数说明

字段	描述
author	作者，长度不超过8个字符，可选
title	标题，长度不超过50个字，必填
cover	图片参数，必填
cover.source_id	图片上传到内容服务后返回的dentryId，必填
cover.mime	图片格式（参考HTTP mime定义），必填
cover.width	图片宽度(pixel)，必填
cover.height	图片高度(pixel)，必填
cover.size	图片大小(byte)，必填
cover.title	图片标题，长度不超过64个字符，必填
cover.md5	图片文件md5，必填
summary	摘要，长度不超过120个字，单图文添加或修改素材时可选，多图文不填
content	图文正文内容，长度不超过20000个字，添加或修改素材时必填
from_url	原文链接，可选

6.返回示例

  {
    "material_id":123
  }

7.返回说明

字段	描述
material_id	素材ID

错误返回码code详见全局错误返回说明

修改素材

1.功能说明

对图片标题、语音标题、图文信息进行修改。

2.请求方式

http请求方式：PATCH

3.请求地址

http://official-account.edu.web.sdp.101.com/app/materials/{material_id}

4.请求数据

  //图片
  {
    "type":"image",
    "content":{
      "title":"图片标题"
    }
  }
  //语音
  {
    "type":"audio",
    "content":{
      "title":"语音标题"
    }
  }
  //图文
  {
    "type":"article",
    "content": [
      {
        "article_id":123,
        "author":"作者",
        "title":"标题",
        "cover": {
          "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
          "mime":"jpeg",
          "width":240,
          "height":320,
          "size":1201024,
          "title":"图片标题",
          "md5":"1146ccc9a0e484f59ff14f8b654f81e1"
        },
        "summary":"xxx",
        "content":"图文正文内容",
        "from_url":"http://www.baidu.com"
      },
      ... //单图文一个，多图文多个，最多不超过8个
    ]
  }

5.参数说明

//图片

参数	描述
type	素材类型，图片素材为image
title	图片标题，长度不超过64个字符，必填

//语音

参数	描述
type	素材类型，语音素材为audio
title	标题，1~20个字符，必填

//图文

参数	描述
type	素材类型，图文素材为article，必填
article_id	图文唯一标识，可选，修改时有填则覆盖原来的图文，不传则重新生成一条图文
author	作者，长度不超过8个字符，可选
title	标题，长度不超过50个字，必填
cover	图片参数，必填
cover.source_id	图片上传到内容服务后返回的dentryId，必填
cover.mime	图片格式（参考HTTP mime定义），必填
cover.width	图片宽度(pixel)，必填
cover.height	图片高度(pixel)，必填
cover.size	图片大小(byte)，必填
cover.title	图片标题，长度不超过64个字符，必填
cover.md5	图片文件md5，必填
summary	摘要，长度不超过120个字，单图文添加或修改素材时可选，多图文不填
content	图文正文内容，长度不超过20000个字，添加或修改素材时必填
from_url	原文链接，可选

6.返回示例

  {
    "material_id":123
  }

7.返回说明

字段	描述
material_id	素材ID

错误返回码code详见全局错误返回说明

删除素材

1.功能说明

通过本接口可以删除公众号素材。

2.请求方式

http请求方式：DELETE

3.请求地址

http://official-account.edu.web.sdp.101.com/app/materials/{material_id}

4.请求数据

无

5.参数说明

无

6.返回示例

  {
    "material_id":123
  }

7.返回说明

字段	描述
material_id	素材ID

错误返回码code详见全局错误返回说明

获取素材列表

1.功能说明

获取单个素材详细信息。

2.请求方式

http请求方式：GET

3.请求地址

http://official-account.edu.web.sdp.101.com/app/materials?type={type}[&$offset={offset}][&$limit={limit}]

4.请求数据

无

5.参数说明

参数	描述
type	素材类型，图片（image）、图文（article），必填
$offset	从0开始，获取位置偏移，可选
$limit	返回条数，缺省为10条，可选,最大值不超过100

6.返回示例

  //图片
  {
    "count":100,
    "items":[
      {
        "material_id":12323,
        "update_time":123,
        "type":"image",
        "content":{
          "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
          "mime":"jpeg",
          "width":240,
          "height":320,
          "size":1201024,
          "title":"图片标题",
          "md5":"1146ccc9a0e484f59ff14f8b654f81e1"
        }
      },
      ...
    ]
  }
  //语音
  {
    "count":100,
    "items":[
      {
        "material_id":12323,
        "update_time":123,
        "type":"image",
        "content":{
          "title":"标题",
            "src":"c9836767-a64e-439b-a689-13c5f7adeb6f",
            "mime":"amr",
            "dura":12,
            "size":3076,
            "md5":"bcb31b38e4c01691881e38023dea69e9"
        }
      },
      ...
    ]
  }
  //图文
  {
    "count":100,
    "items":[
      {
        "material_id":12323,
        "update_time":123,
        "type":"image",
        "content": [
          {
            "article_id":123,
            "href": "http://xxx",
            "author":"作者",
            "title":"标题",
            "cover": {
              "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
              "mime":"jpeg",
              "width":240,
              "height":320,
              "size":1201024,
              "title":"图片标题",
              "md5":"1146ccc9a0e484f59ff14f8b654f81e1"
            },
            "summary":"xxx",
            "from_url":"http://www.baidu.com"
          },
            ...
        ]
      },
      ...
    ]
  }

7.返回说明

//图片

字段	描述
count	素材总数
material_id	素材ID
update_time	素材修改时间
type	素材类型，图片素材为image
source_id	图片上传到内容服务后返回的dentryId
mime	图片格式（参考HTTP mime定义）
width	图片宽度(pixel)
height	图片高度(pixel)
size	图片大小(byte)
title	图片标题，长度不超过64个字符
md5	图片文件md5

//语音

字段	描述
count	素材总数
material_id	素材ID
update_time	素材修改时间
type	素材类型，语音素材为audio
src	语音上传到内容服务后返回的dentryId
mime	语音格式（参考HTTP mime定义）
dura	音频持续时间
size	图片高度(pixel)
size	音频文件大小(byte)
md5	语音文件md5

//图文

字段	描述
count	素材总数
material_id	素材ID
update_time	素材修改时间
type	素材类型，图文素材为article
author	作者，长度不超过8个字符
title	标题，长度不超过50个字
cover	图片参数
cover.source_id	图片上传到内容服务后返回的dentryId
cover.mime	图片格式（参考HTTP mime定义）
cover.width	图片宽度(pixel)
cover.height	图片高度(pixel)
cover.size	图片大小(byte)
cover.title	图片标题，长度不超过64个字符，必填
cover.md5	图片文件md5，必填
summary	摘要
from_url	原文链接

错误返回码code详见全局错误返回说明

获取素材详细信息

1.功能说明

获取单个素材详细信息。

2.请求方式

http请求方式：GET

3.请求地址

http://official-account.edu.web.sdp.101.com/app/materials/{material_id}

4.请求数据

无

5.参数说明

参数	描述
material_id	素材ID

6.返回示例

  //图片
  {
    "material_id":12323,
    "update_time":123,
    "type":"image",
    "content":{
      "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
      "mime":"jpeg",
      "width":240,
      "height":320,
      "size":1201024,
      "title":"图片标题",
      "md5":"1146ccc9a0e484f59ff14f8b654f81e1"
    }
  }
  //语音
  {
    "material_id":12323,
    "update_time":123,
    "type":"image",
    "content":{
      "title":"标题",
        "src":"c9836767-a64e-439b-a689-13c5f7adeb6f",
        "mime":"amr",
        "dura":12,
        "size":3076,
        "md5":"bcb31b38e4c01691881e38023dea69e9"
    }
  }
  //图文
  {
    "material_id":12323,
    "update_time":123,
    "type":"image",
    "content": [
      {
        "article_id":123,
        "href": "http://xxx",
        "author":"作者",
        "title":"标题",
        "cover": {
          "source_id":"96340084-775d-4740-ae3f-b2dea289618b",
          "mime":"jpeg",
          "width":240,
          "height":320,
          "size":1201024,
          "title":"图片标题",
          "md5":"1146ccc9a0e484f59ff14f8b654f81e1"
        },
        "summary":"xxx",
        "from_url":"http://www.baidu.com"
      },
        ...
    ]
  }

7.返回说明

//图片

字段	描述
material_id	素材ID
update_time	素材修改时间
type	素材类型，图片素材为image
source_id	图片上传到内容服务后返回的dentryId
mime	图片格式（参考HTTP mime定义）
width	图片宽度(pixel)
height	图片高度(pixel)
size	图片大小(byte)
title	图片标题，长度不超过64个字符
md5	图片文件md5

//语音

字段	描述
material_id	素材ID
update_time	素材修改时间
type	素材类型，语音素材为audio
src	语音上传到内容服务后返回的dentryId
mime	语音格式（参考HTTP mime定义）
dura	音频持续时间
size	图片高度(pixel)
size	音频文件大小(byte)
md5	语音文件md5

//图文

字段	描述
material_id	素材ID
update_time	素材修改时间
type	素材类型，图文素材为article
author	作者，长度不超过8个字符
title	标题，长度不超过50个字
cover	图片参数
cover.source_id	图片上传到内容服务后返回的dentryId
cover.mime	图片格式（参考HTTP mime定义）
cover.width	图片宽度(pixel)
cover.height	图片高度(pixel)
cover.size	图片大小(byte)
cover.title	图片标题，长度不超过64个字符，必填
cover.md5	图片文件md5，必填
summary	摘要
from_url	原文链接

错误返回码code详见全局错误返回说明

五、用户分组管理

获取用户列表

1.功能说明

开发者通过本接口获取订阅号关注用户列表和应用号分组用户列表。

2.请求方式

http请求方式：GET

3.请求地址

http://official-account.edu.web.sdp.101.com/app/users[?$offset={$offset}][&$limit={$limit}][&tag_id={tag_id}]

4.请求数据

无

5.参数说明

参数	描述
tag_id	用户分组ID，订阅号可选，默认取全部关注用户，0为未分组关注用户，大于0取指定分组关注用户；应用号必填，取指定分组用户
$offset	从0开始，获取位置偏移，可选，默认为0
$limit	返回条数，可选，默认为10条，最大值不超过100

6.返回示例

  {
    "count": 20 ,
    "items":[
      {
        "user_id":123456,
        "tag_id":123,
        "remark":"xxxxxxx",
        "nick_name":"xxx"
      },
      ...
    ]
  }

7.返回说明

字段	描述
count	该查询条件下用户总数
user_id	用户ID
tag_id	用户分组ID，订阅号未分组关注用户为0
remark	用户备注
nick_name	用户昵称

错误返回码code详见全局错误返回说明

获取分组列表

1.功能说明

开发者通过本接口可以获取所有用户分组。

2.请求方式

http请求方式：GET

3.请求地址

http://official-account.edu.web.sdp.101.com/app/tags

4.请求数据

无

5.参数说明

无

6.返回示例

  {
    "items":[
      {
        "tag_id":123,
        "name":"VIP组",
        "sub_count":123,
        "type":"NORMAL"
      },
      ...
    ]
  }

7.返回说明

字段	描述
tag_id	分组ID
name	分组名称
sub_count	分组用户数
type	分组类型，NORMAL普通分组、STAR星标组，公众号默认有星标组

错误返回码code详见全局错误返回说明

创建分组

1.功能说明

开发者通过本接口可以创建用户分组，最多创建10分组（包括星标组在内），且只能创建NORMAL类型分组。

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/tags

4.请求数据

  {
    "name":"VIP组"
  }

5.参数说明

参数	描述
name	分组名称，1~20个字符，必填

6.返回示例

  {
    "tag_id":123
  }

7.返回说明

字段	描述
tag_id	分组ID

错误返回码code详见全局错误返回说明

修改分组

1.功能说明

开发者通过本接口可以修改用户分组名，只能修改NORMAL类型分组。

2.请求方式

http请求方式：PATCH

3.请求地址

http://official-account.edu.web.sdp.101.com/app/tags/{tag_id}

4.请求数据

  {
    "name":"VIP组"
  }

5.参数说明

参数	描述
name	分组名称，1~20个字符，必填
tag_id	分组ID，必填

6.返回示例

  {
    "tag_id":123
  }

7.返回说明

字段	描述
tag_id	分组ID

错误返回码code详见全局错误返回说明

删除分组

1.功能说明

开发者通过本接口可以删除用户分组，订阅号删除分组后，关注用户为未分组，应用号删除后，用户无分组。

2.请求方式

http请求方式：DELETE

3.请求地址

http://official-account.edu.web.sdp.101.com/app/tags/{tag_id}

4.请求数据

无

5.参数说明

无

6.返回示例

  {
    "tag_id":123
  }

7.返回说明

字段	描述
tag_id	分组ID

错误返回码code详见全局错误返回说明

指定用户加入分组

1.功能说明

开发者可以通过本接口指定用户修改用户分组，订阅号关注用户默认分组ID为0（未分组）；应用号指定用户加入分组，为0时表示从用户分组中删除用户。

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/tags/{tag_id}/actions/join

4.请求数据

  {
    "user_ids":[
      123,
      456
    ]
  }
  或
  {
    "login_names":[
      "123@nd",
      "456@nd"
    ]
  }

5.参数说明

参数	描述
user_ids	用户ID数组，user_ids与login_names二选一
login_names	用户登录名，即工号@org_name或手机号@org_name或用户名@org_name，user_id与login_name二选一

6.返回示例

  {
    "tag_id":123
  }

7.返回说明

字段	描述
tag_id	分组ID

错误返回码code详见全局错误返回说明

六、菜单管理

创建菜单

1.功能说明

自定义菜单能够帮助公众号完成更多功能，使用户更快了解公众号的用途。开发者通过本接口配置菜单默认为菜单启用状态。自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二级菜单，一级菜单不多于4个汉字或8个字母，二级菜单不多于8个汉字或16个字母。

2.请求方式

http请求方式：POST

3.请求地址

http://official-account.edu.web.sdp.101.com/app/messages/menus

4.请求数据

{
  "buttons": [
    {
      "type": "click",
      "name": "一级菜单",
      "key": "V1000_BUTTON",
    },
    {
      "type": "view",
      "name": "view_url",
      "url": "http://www.qq.com",
    },
    {
      "name": "菜单",
      "sub_buttons": [
        {
          "type": "view",
          "name": "百度一下",
          "url": "http://www.baidu.com/"
        },
        {
          "type": "click",
          "name": "赞一下我们",
          "key": "V3002_SUB_BUTTON"
        }
      ]
    }
  ]
}

5.参数说明

参数	描述
buttons	父菜单按钮数组，按钮个数不超过3个，无菜单按钮时为{"buttons": []}，
type	按钮类型，目前支持view、click类型,view类型跳转到URL，click类型点击发送事件消息，格式参考接收消息中事件消息说明
name	按钮描述，即按钮名称，一级菜单不多于4个汉字或8个字母，二级菜单不多于8个汉字或16个字母
key	按钮KEY值，用于消息接口(event类型)推送，类型为click时必填，key值不能重复；通过公众号后台设置菜单key为默认值
url	跳转url，type为view时必填
sub_buttons	子菜单按钮数组，按钮个数应为1~5个(可选)

6.返回示例

  {
    "oa_id":123
  }

7.返回说明

字段	描述
oa_id	公众号编号

错误返回码code详见全局错误返回说明

删除菜单

1.功能说明

开发者通过本接口可以删除公众号菜单，删除菜单后，客户端不再显示菜单按钮。

2.请求方式

http请求方式：DELETE

3.请求地址

http://official-account.edu.web.sdp.101.com/app/messages/menus

4.请求数据

无

5.参数说明

无

6.返回示例

  {
    "oa_id":123
  }

7.返回说明

字段	描述
oa_id	公众号编号

错误返回码code详见全局错误返回说明

获取菜单

1.功能说明

开发者通过本接口获取已创建的菜单，若未通过第三方接口创建菜单，则获取的菜单为编辑模式下发布的菜单或为空。

2.请求方式

http请求方式：GET

3.请求地址

http://official-account.edu.web.sdp.101.com/app/messages/menus

4.请求数据

无

5.参数说明

无

6.返回示例

 {
  "buttons": [
    {
      "type": "click",
      "name": "一级菜单",
      "key": "V1000_BUTTON",
    },
    {
      "type": "view",
      "name": "view_url",
      "url": "http://www.qq.com",
    },
    {
      "name": "菜单",
      "sub_buttons": [
        {
          "type": "view",
          "name": "百度一下",
          "url": "http://www.baidu.com/"
        },
        {
          "type": "click",
          "name": "赞一下我们",
          "key": "V3002_SUB_BUTTON"
        }
      ]
    }
  ]
  }

7.返回说明

字段	描述
buttons	父菜单按钮数组，按钮个数不超过3个，无菜单按钮时为{"buttons": []}，
type	按钮类型，目前支持view、click类型,view类型跳转到URL，click类型点击发送事件消息，格式参考接收消息中事件消息说明
name	按钮描述，即按钮名称，一级菜单不多于4个汉字或8个字母，二级菜单不多于8个汉字或16个字母
key	按钮KEY值，用于消息接口(event类型)推送，类型为click时必填，key值不能重复；通过公众号后台设置菜单key为默认值
url	跳转url，type为view时必填
sub_buttons	子菜单按钮数组，按钮个数应为1~5个(可选)

错误返回码code详见全局错误返回说明