微信公众平台开发模式自定义菜单接口API指南

亦凉 2022-06-12 11:38 211阅读 0赞

# **微信公众平台开发模式自定义菜单接口API指南** #

开发实现方法，请查看

# [微信公众平台开发（58）自定义菜单][58] #

# #

## **简介** ##

开发者获取使用凭证（[如何获取凭证][Link 1]）后，可以使用该凭证对公众账号的自定义菜单进行创建、查询和删除等操作。 自定义菜单接口可实现以下类型按钮：

click（点击事件）：

用户点击click类型按钮后，微信服务器会通过消息接口(event类型)推送点击事件给开发者，并且带上按钮中开发者填写的key值，开发者可以通过自定义的key值进行消息回复。

创建自定义菜单后，由于微信客户端缓存，需要24小时微信客户端才会展现出来。建议测试时可以尝试取消关注公众账号后，再次关注，则可以看到创建后的效果。

## **菜单创建** ##

**接口说明**

通过POST一个特定结构体，实现在微信客户端创建自定义菜单。

**请求说明**

http请求方式：POST
    https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN

**请求示例**

{
         "button":[
         {	
              "type":"click",
              "name":"今日歌曲",
              "key":"V1001_TODAY_MUSIC"
          },
          {
               "type":"click",
               "name":"歌手简介",
               "key":"V1001_TODAY_SINGER"
          },
          {
               "name":"菜单",
               "sub_button":[
                {
                   "type":"click",
                   "name":"hello word",
                   "key":"V1001_HELLO_WORLD"
                },
                {
                   "type":"click",
                   "name":"赞一下我们",
                   "key":"V1001_GOOD"
                }]
           }]
     }

创建后效果:

**参数说明**

<table style=""> 
 <tbody> 
  <tr> 
   <th style="width:120px">参数</th> 
   <th style="width:120px">是否必须</th> 
   <th>说明</th> 
  </tr> 
  <tr> 
   <td>button</td> 
   <td>是</td> 
   <td>按钮数组，按钮个数应为1~3个</td> 
  </tr> 
  <tr> 
   <td>sub_button</td> 
   <td>否</td> 
   <td>子按钮数组，按钮个数应为1~5个</td> 
  </tr> 
  <tr> 
   <td>type</td> 
   <td>是</td> 
   <td>按钮类型，目前有click类型</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>是</td> 
   <td>按钮描述，既按钮名字，不超过16个字节，子菜单不超过40个字节</td> 
  </tr> 
  <tr> 
   <td>key</td> 
   <td>类型为click必须</td> 
   <td>按钮KEY值，用于<a href="http://mp.weixin.qq.com/wiki/index.php?title=%E6%B6%88%E6%81%AF%E6%8E%A5%E5%8F%A3%E6%8C%87%E5%8D%97#.E4.BA.8B.E4.BB.B6.E6.8E.A8.E9.80.81" style="color:#366799; text-decoration:none" rel="nofollow">消息接口(event类型)</a>推送，不超过128字节</td> 
  </tr> 
 </tbody> 
</table>

**返回说明**

正确的Json返回结果:

{"errcode":0,"errmsg":"ok"}

错误的Json返回结果

{"errcode":40018,"errmsg":"invalid button name size"}

[统一返回码说明][Link 2]

## **菜单查询** ##

**接口说明**

查询当前使用的自定义菜单结构。

**请求说明**

http请求方式：GET
    https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN

**返回说明**

对应创建接口，正确的Json返回结果:
    {"menu":{"button":[{"type":"click","name":"今日歌曲","key":"V1001_TODAY_MUSIC","sub_button":[]},{"type":"click","name":"歌手简介","key":"V1001_TODAY_SINGER","sub_button":[]},{"name":"菜单","sub_button":[{"type":"click","name":"hello word","key":"V1001_HELLO_WORLD","sub_button":[]},{"type":"click","name":"赞一下我们","key":"V1001_GOOD","sub_button":[]}]}]}}

[统一返回码说明][Link 2]

## **菜单删除** ##

**接口说明**

取消当前使用的自定义菜单。

**请求说明**

http请求方式：GET
    https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

**返回说明**

对应创建接口，正确的Json返回结果:
    {"errcode":0,"errmsg":"ok"}

[统一返回码说明][Link 2]

请先确保公众账号已经拥有接口调用权限。

默认每个公众帐号都不能超过下面的频率限制。 当超出调用接口频率限制，调用对应接口将会收到如下错误信息：

{"errcode":45009,"errmsg":"api freq out of limit"}

## **接口调用频率限制** ##

<table style=""> 
 <tbody> 
  <tr> 
   <th style="width:320px">接口名称</th> 
   <th style="width:320px">频率限制</th> 
  </tr> 
  <tr> 
   <td><a href="http://mp.weixin.qq.com/wiki/index.php?title=%E9%80%9A%E7%94%A8%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3#.E8.8E.B7.E5.8F.96.E5.87.AD.E8.AF.81" style="color:#366799; text-decoration:none" rel="nofollow">获取凭证接口</a></td> 
   <td>200（次/天）</td> 
  </tr> 
  <tr> 
   <td><a href="http://mp.weixin.qq.com/wiki/index.php?title=%E8%87%AA%E5%AE%9A%E4%B9%89%E8%8F%9C%E5%8D%95%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3#.E8.8F.9C.E5.8D.95.E5.88.9B.E5.BB.BA" style="color:#366799; text-decoration:none" rel="nofollow">自定义菜单创建接口</a></td> 
   <td>100（次/天）</td> 
  </tr> 
  <tr> 
   <td><a href="http://mp.weixin.qq.com/wiki/index.php?title=%E8%87%AA%E5%AE%9A%E4%B9%89%E8%8F%9C%E5%8D%95%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3#.E8.8F.9C.E5.8D.95.E6.9F.A5.E8.AF.A2" style="color:#366799; text-decoration:none" rel="nofollow">自定义菜单查询接口</a></td> 
   <td>1000（次/天）</td> 
  </tr> 
  <tr> 
   <td><a href="http://mp.weixin.qq.com/wiki/index.php?title=%E8%87%AA%E5%AE%9A%E4%B9%89%E8%8F%9C%E5%8D%95%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3#.E8.8F.9C.E5.8D.95.E5.88.A0.E9.99.A4" style="color:#366799; text-decoration:none" rel="nofollow">自定义菜单删除接口</a></td> 
   <td>100（次/天）</td> 
  </tr> 
 </tbody> 
</table>

### 返回码说明 ###

<table style=""> 
 <tbody> 
  <tr> 
   <th style="width:120px">返回码</th> 
   <th>说明</th> 
  </tr> 
  <tr> 
   <td>-1</td> 
   <td>系统繁忙</td> 
  </tr> 
  <tr> 
   <td>0</td> 
   <td>请求成功</td> 
  </tr> 
  <tr> 
   <td>40001</td> 
   <td>验证失败</td> 
  </tr> 
  <tr> 
   <td>40002</td> 
   <td>不合法的凭证类型</td> 
  </tr> 
  <tr> 
   <td>40003</td> 
   <td>不合法的OpenID</td> 
  </tr> 
  <tr> 
   <td>40004</td> 
   <td>不合法的媒体文件类型</td> 
  </tr> 
  <tr> 
   <td>40005</td> 
   <td>不合法的文件类型</td> 
  </tr> 
  <tr> 
   <td>40006</td> 
   <td>不合法的文件大小</td> 
  </tr> 
  <tr> 
   <td>40007</td> 
   <td>不合法的媒体文件id</td> 
  </tr> 
  <tr> 
   <td>40008</td> 
   <td>不合法的消息类型</td> 
  </tr> 
  <tr> 
   <td>40009</td> 
   <td>不合法的图片文件大小</td> 
  </tr> 
  <tr> 
   <td>40010</td> 
   <td>不合法的语音文件大小</td> 
  </tr> 
  <tr> 
   <td>40011</td> 
   <td>不合法的视频文件大小</td> 
  </tr> 
  <tr> 
   <td>40012</td> 
   <td>不合法的缩略图文件大小</td> 
  </tr> 
  <tr> 
   <td>40013</td> 
   <td>不合法的APPID</td> 
  </tr> 
  <tr> 
   <td>40014</td> 
   <td>不合法的access_token</td> 
  </tr> 
  <tr> 
   <td>40014</td> 
   <td>不合法的access_token</td> 
  </tr> 
  <tr> 
   <td>40015</td> 
   <td>不合法的菜单类型</td> 
  </tr> 
  <tr> 
   <td>40016</td> 
   <td>不合法的按钮个数</td> 
  </tr> 
  <tr> 
   <td>40017</td> 
   <td>不合法的按钮个数</td> 
  </tr> 
  <tr> 
   <td>40018</td> 
   <td>不合法的按钮名字长度</td> 
  </tr> 
  <tr> 
   <td>40019</td> 
   <td>不合法的按钮KEY长度</td> 
  </tr> 
  <tr> 
   <td>40020</td> 
   <td>不合法的按钮URL长度</td> 
  </tr> 
  <tr> 
   <td>40021</td> 
   <td>不合法的菜单版本号</td> 
  </tr> 
  <tr> 
   <td>40022</td> 
   <td>不合法的子菜单级数</td> 
  </tr> 
  <tr> 
   <td>40023</td> 
   <td>不合法的子菜单按钮个数</td> 
  </tr> 
  <tr> 
   <td>40024</td> 
   <td>不合法的子菜单按钮类型</td> 
  </tr> 
  <tr> 
   <td>40025</td> 
   <td>不合法的子菜单按钮名字长度</td> 
  </tr> 
  <tr> 
   <td>40026</td> 
   <td>不合法的子菜单按钮KEY长度</td> 
  </tr> 
  <tr> 
   <td>40027</td> 
   <td>不合法的子菜单按钮URL长度</td> 
  </tr> 
  <tr> 
   <td>40028</td> 
   <td>不合法的自定义菜单使用用户</td> 
  </tr> 
  <tr> 
   <td>41001</td> 
   <td>缺少access_token参数</td> 
  </tr> 
  <tr> 
   <td>41002</td> 
   <td>缺少appid参数</td> 
  </tr> 
  <tr> 
   <td>41003</td> 
   <td>缺少refresh_token参数</td> 
  </tr> 
  <tr> 
   <td>41004</td> 
   <td>缺少secret参数</td> 
  </tr> 
  <tr> 
   <td>41005</td> 
   <td>缺少多媒体文件数据</td> 
  </tr> 
  <tr> 
   <td>41006</td> 
   <td>缺少media_id参数</td> 
  </tr> 
  <tr> 
   <td>41007</td> 
   <td>缺少子菜单数据</td> 
  </tr> 
  <tr> 
   <td>42001</td> 
   <td>access_token超时</td> 
  </tr> 
  <tr> 
   <td>43001</td> 
   <td>需要GET请求</td> 
  </tr> 
  <tr> 
   <td>43002</td> 
   <td>需要POST请求</td> 
  </tr> 
  <tr> 
   <td>43003</td> 
   <td>需要HTTPS请求</td> 
  </tr> 
  <tr> 
   <td>44001</td> 
   <td>多媒体文件为空</td> 
  </tr> 
  <tr> 
   <td>44002</td> 
   <td>POST的数据包为空</td> 
  </tr> 
  <tr> 
   <td>44003</td> 
   <td>图文消息内容为空</td> 
  </tr> 
  <tr> 
   <td>45001</td> 
   <td>多媒体文件大小超过限制</td> 
  </tr> 
  <tr> 
   <td>45002</td> 
   <td>消息内容超过限制</td> 
  </tr> 
  <tr> 
   <td>45003</td> 
   <td>标题字段超过限制</td> 
  </tr> 
  <tr> 
   <td>45004</td> 
   <td>描述字段超过限制</td> 
  </tr> 
  <tr> 
   <td>45005</td> 
   <td>链接字段超过限制</td> 
  </tr> 
  <tr> 
   <td>45006</td> 
   <td>图片链接字段超过限制</td> 
  </tr> 
  <tr> 
   <td>45007</td> 
   <td>语音播放时间超过限制</td> 
  </tr> 
  <tr> 
   <td>45008</td> 
   <td>图文消息超过限制</td> 
  </tr> 
  <tr> 
   <td>45009</td> 
   <td>接口调用超过限制</td> 
  </tr> 
  <tr> 
   <td>45010</td> 
   <td>创建菜单个数超过限制</td> 
  </tr> 
  <tr> 
   <td>46001</td> 
   <td>不存在媒体数据</td> 
  </tr> 
  <tr> 
   <td>46002</td> 
   <td>不存在的菜单版本</td> 
  </tr> 
  <tr> 
   <td>46003</td> 
   <td>不存在的菜单数据</td> 
  </tr> 
  <tr> 
   <td>47001</td> 
   <td>解析JSON/XML内容错误</td> 
  </tr> 
 </tbody> 
</table>

**源代码：**

# [微信公众平台消息接口开发（9）自定义菜单][9] #

[58]: http://www.cnblogs.com/txw1958/p/weixin-58-custom-menu.html
[Link 1]: http://mp.weixin.qq.com/wiki/index.php?title=%E9%80%9A%E7%94%A8%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3
[Link 2]: http://mp.weixin.qq.com/wiki/index.php?title=%E8%BF%94%E5%9B%9E%E7%A0%81%E8%AF%B4%E6%98%8E
[9]: http://www.cnblogs.com/txw1958/archive/2013/03/12/weixin-if9-CustomizeMenus.html