# 创建个性化菜单

接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南

接口英文名：addConditionalMenu

为了帮助公众号实现灵活的业务运营，微信公众平台新增了个性化菜单接口，开发者可以通过该接口，让公众号的不同用户群体看到不一样的自定义菜单。

开发者可以通过以下条件来设置用户看到的菜单：

用户标签（开发者的业务需求可以借助用户标签来完成）
使用普通自定义菜单查询接口可以获取默认菜单和全部个性化菜单信息，请见自定义菜单查询接口的说明。
使用普通自定义菜单删除接口可以删除所有自定义菜单（包括默认菜单和全部个性化菜单），请见自定义菜单删除接口的说明。

注意：为保护个人隐私，公众号个性化菜单将不再支持对性别、地区、语言这类涉及个人隐私数据的信息进行筛选的功能，具体调整如下：

创建时，只要匹配条件中包含隐私信息的，将被拒绝，并返回错误码 65320；

已经创建的，如包含隐私信息的则自动失效，不包含的则正常匹配；

开发者仍然可以正常通过测试接口，获取到粉丝看到的菜单；

查询个性化菜单时，所有规则正常显示。

# 1. 调用方式

# HTTPS 调用

POST https://api.weixin.qq.com/cgi-bin/menu/addconditional?access_token=ACCESS_TOKEN

# 云调用

调用方法：officialAccount.menu.addConditional
出入参和 HTTPS 调用相同，调用方式可查看云调用说明文档

# 第三方调用

本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为：15
服务商获得其中之一权限集授权后，可通过使用 authorizer_access_token 代商家进行调用，具体可查看第三方调用说明文档。

# 2. 请求参数

# 查询参数 `Query String parameters`

参数名	类型	必填	示例	说明
access_token	string	是	ACCESS_TOKEN	接口调用凭证，可使用 access_token、authorizer_access_token

# 请求体 `Request Payload`

参数名	类型	必填	说明
button	objarray	是	一级菜单数组(1-3个)
matchrule	object	是	菜单匹配规则(至少一个非空字段)

# Body.button(Array) `Object Payload`

参数名	类型	必填	示例	说明
type	string	否	click	菜单的响应动作类型（与 sub_button 互斥）
name	string	是	今日歌曲	菜单标题，不超过16个字节，子菜单不超过60个字节
key	string	否	-	菜单KEY值，用于消息接口推送，不超过128字节。click等点击类型必须。
url	string	否	-	网页链接，用户点击菜单可打开链接，不超过1024字节。 type为miniprogram时，不支持小程序的老版本客户端将打开本url。view、miniprogram类型必填。
media_id	string	否	-	调用新增永久素材接口返回的合法media_id。media_id类型和view_limited类型必须
appid	string	否	-	小程序的appid（仅认证公众号可配置），miniprogram类型必须
pagepath	string	否	-	小程序的页面路径，miniprogram类型必须
article_id	string	否	-	发布后获得的合法 article_id，article_id类型和article_view_limited类型必须
sub_button	objarray	否	-	二级菜单结构体数组

# Body.matchrule `Object Payload`

菜单匹配规则(至少一个非空字段)

参数名	类型	必填	示例	说明
tag_id	string	否	-	用户标签的id，可通过用户标签管理接口获取
client_platform_type	string	否	1	客户端版本，当前只具体到系统型号：IOS(1), Android(2),Others(3)，不填则不做匹配

# Body.button(Array).sub_button`Object Payload`

二级菜单结构体数组

参数名	类型	必填	示例	说明
type	string	是	click	菜单的响应动作类型（同一级菜单的 type）
name	string	是	今日歌曲	菜单标题，不超过16个字节，子菜单不超过60个字节
key	string	否	-	菜单KEY值，用于消息接口推送，不超过128字节。click等点击类型必须。
url	string	否	-	网页链接，用户点击菜单可打开链接，不超过1024字节。 type为miniprogram时，不支持小程序的老版本客户端将打开本url。view、miniprogram类型必填。
media_id	string	否	-	调用新增永久素材接口返回的合法media_id。media_id类型和view_limited类型必须
appid	string	否	-	小程序的appid（仅认证公众号可配置），miniprogram类型必须
pagepath	string	否	-	小程序的页面路径，miniprogram类型必须
article_id	string	否	-	发布后获得的合法 article_id，article_id类型和article_view_limited类型必须

# 3. 返回参数

# 返回体 `Response Payload`

参数名	类型	示例	说明
menuid	string	208379533	菜单ID
errcode	number	-	错误码
errmsg	string	-	错误描述

# 4. 注意事项

个性化菜单要求用户的微信客户端版本在iPhone6.2.2，Android 6.2.4以上，暂时不支持其他版本微信
菜单的刷新策略是，在用户进入公众号会话页或公众号profile页时，如果发现上一次拉取菜单的请求在5分钟以前，就会拉取一下菜单，如果菜单有更新，就会刷新客户端的菜单。测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果
普通公众号的个性化菜单的新增接口每日限制次数为2000次，删除接口也是2000次，测试个性化菜单匹配结果接口为20000次
出于安全考虑，一个公众号的所有个性化菜单，最多只能设置为跳转到3个域名下的链接
创建个性化菜单之前必须先创建默认菜单（默认菜单是指使用普通自定义菜单创建接口创建的菜单）。如果删除默认菜单，个性化菜单也会全部删除
个性化菜单接口支持用户标签，请开发者注意，当用户身上的标签超过1个时，以最后打上的标签为匹配

个性化菜单的更新是会被覆盖的。例如公众号先后发布了默认菜单，个性化菜单1，个性化菜单2，个性化菜单3。那么当用户进入公众号页面时，将从个性化菜单3开始匹配，如果个性化菜单3匹配成功，则直接返回个性化菜单3，否则继续尝试匹配个性化菜单2，直到成功匹配到一个菜单。根据上述匹配规则，为了避免菜单生效时间的混淆，决定不予提供个性化菜单编辑API，开发者需要更新菜单时，需将完整配置重新发布一轮。

# 补充说明

button中将不再支持图文(news)类型永久素材的 media_id，请使用 article_id 代替 matchrule共七个字段，均可为空，但不能全部为空，至少要有一个匹配信息是不为空的。 country、province、city组成地区信息，将按照country、province、city的顺序进行验证，要符合地区信息表的内容。地区信息从大到小验证，小的可以不填，即若填写了省份信息，则国家信息也必填并且匹配，城市信息可以不填。例如 “中国广东省广州市”、“中国广东省”都是合法的地域信息，而“中国广州市”则不合法，因为填写了城市信息但没有填写省份信息。地区信息表请点击下载。

# 5. 代码示例

# 5.1 创建成功返回

请求示例

{
    "button": [
        {
            "type": "click",
            "name": "今日歌曲",
            "key": "V1001_TODAY_MUSIC"
        },
        {
            "name": "菜单",
            "sub_button": [
                {
                    "type": "view",
                    "name": "搜索",
                    "url": "http://www.soso.com/"
                },
                {
                    "type": "miniprogram",
                    "name": "wxa",
                    "url": "http://mp.weixin.qq.com",
                    "appid": "wx286b93c14bbf93aa",
                    "pagepath": "pages/lunar/index"
                },
                {
                    "type": "click",
                    "name": "赞一下我们",
                    "key": "V1001_GOOD"
                }
            ]
        }
    ],
    "matchrule": {
        "tag_id": "2",
        "sex": "1",
        "country": "中国",
        "province": "广东",
        "city": "广州",
        "client_platform_type": "2",
        "language": "zh_CN"
    }
}

返回示例

{
  "menuid": "208379533"
}

# 5.2 创建失败返回

请求示例

{
    "button": [
        {
            "type": "click",
            "name": "今日歌曲",
            "key": "V1001_TODAY_MUSIC"
        },
        {
            "name": "菜单",
            "sub_button": [
                {
                    "type": "view",
                    "name": "搜索",
                    "url": "http://www.soso.com/"
                },
                {
                    "type": "miniprogram",
                    "name": "wxa",
                    "url": "http://mp.weixin.qq.com",
                    "appid": "wx286b93c14bbf93aa",
                    "pagepath": "pages/lunar/index"
                },
                {
                    "type": "click",
                    "name": "赞一下我们",
                    "key": "V1001_GOOD"
                }
            ]
        }
    ],
    "matchrule": {
        "tag_id": "2",
        "sex": "1",
        "country": "中国",
        "province": "广东",
        "city": "广州",
        "client_platform_type": "2",
        "language": "zh_CN"
    }
}

返回示例

{
  "errcode":65320,
  "errmsg":"match rule violates privacy"
}

# 6. 错误码

以下是本接口的错误码列表，其他错误码可参考通用错误码

错误码	错误描述	解决方案
-1	system error	系统繁忙，此时请开发者稍候再试
40001	invalid credential access_token isinvalid or not latest	获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口
40007	invalid media_id	不合法的媒体文件 id
40016	invalid button size	不合法的按钮个数
40017	invalid button type	不合法的按钮类型
40018	invalid button name size	不合法的按钮名字长度
40019	invalid button key size	不合法的按钮 KEY 长度
40020	invalid button url size	不合法的按钮 URL 长度
40023	invalid sub button size	不合法的子菜单按钮个数
40024	invalid sub button type	不合法的子菜单按钮类型
40027	invalid sub button url size	不合法的子菜单按钮 URL 长度
40033	invalid charset. please check your request if include \uxxxx will create fail!	不合法的请求字符，不能包含 \uxxxx 格式的字符
40054	invalid sub button url domain	不合法的子菜单按钮 url 域名
40055	invalid button url domain	不合法的菜单按钮 url 域名
53600	Article ID 无效	图文ID无效
65320	match rule violates privacy	匹配规则包含隐私字段

# 7. 适用范围

本接口在不同账号类型下的可调用情况：

公众号	服务号
仅认证	仅认证

仅认证：表示仅允许企业主体已认证账号调用，未认证或不支持认证的账号无法调用
其他未明确声明的账号类型，如无特殊说明，均不可调用此接口；