To help Official Account operators run business flexibly, the WeChat Official Accounts Platform provides personalized menu APIs for verified Subscription Accounts and verified Service Accounts. With these APIs, the developer can allow their Official Account to show different custom menus to different groups of users.

The developer can set menus visible to users by using the following conditions:

1. User tag (used to implement the developer's business requirements)
2. Gender
3. Mobile OS
4. Location (set by the user in the WeChat app)
5. Language (set by the user in the WeChat app)

Description of personalized menu APIs:

1. Personalized menu is only supported as of WeChat 6.2.2 for iOS and WeChat 6.2.4 for Android.
2. When a user enters the chat screen or the profile screen of an Official Account, if the last request for pulling the menu is sent 5 minutes ago, the menu will be pulled, and if the menu is updated, then the menu in the app will be refreshed. During testing, you can unfollow the Official Account and then follow it again to view the effect of the created menu.
3. For Official Accounts, the number of times that the developer use the Create Personalized Menu API, the Delete Personalized Menu API and the Test Personalized Menu Match Result API is 2000, 2000 and 20000, respectively.
4. For security reasons, all personalized menus for one Official Account can only be set to redirect to URLs under at most 3 domain names.
5. A default menu (a menu created using the custom menu creation API) must be created before you can create any personalized menu. Deleting the default menu will remove all personalized menus.
6. Personalized Menu APIs support user tags. Note that when a user has more than 1 tag, the last tag is used for match.

Match rule for personalized menus:

A personalized menu will be overwritten by an updated version.
For example, an Official Account publishes the default menu, the personalized menu 1, the personalized menu 2, and the personalized menu 3 in turn. When a user opens the Official Account screen, the system matches the user to the personalized menu 3 first. After the match succeeds, the user returns to the personalized menu 3. Otherwise, the system matches the user to the personalized menu 2, until the user matches a menu.
As per the above match rule, the personalized menu editing API is not provided to avoid the confusion of time when a menu takes effect. To update a menu, the developer needs to publish the entire configuration again.

Contents

1. Create personalized menu

2. Delete personalized menu

3. Test personalized menu match result

4. Query personalized menu

5. Delete all menus

Creating Personalized Menu

HTTP request method: POST (HTTPS protocol should be used)

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

Request example

{
    "button": [
        {
            "type": "click", 
            "name": "Today's songs", 
            "key": "V1001_TODAY_MUSIC"
        }, 
        {
            "name": "Menu", 
            "sub_button": [
                {
                    "type": "view", 
                    "name": "Search", 
                    "url": "http://www.soso.com/"
                }, 
                {
                    "type": "miniprogram", 
                    "name": "wxa", 
                    "url": "http://mp.weixin.qq.com", 
                    "appid": "wx286b93c14bbf93aa", 
                    "pagepath": "pages/lunar/index"
                }, 
                {
                    "type": "click", 
                    "name": "Give us a like", 
                    "key": "V1001_GOOD"
                }
            ]
        }
    ], 
    "matchrule": {
        "tag_id": "2", 
        "sex": "1", 
        "country": "China", 
        "province": "Guangdong", 
        "city": "Guangzhou", 
        "client_platform_type": "2", 
        "language": "zh_CN"
    }
}

Parameters

Parameter Required Description
button Yes The array of primary menus. The number of menus should be between 1 and 3.
sub_button Yes The array of secondary menus. The number of menus should be between 1 and 5.
type Yes Response action type of the menu. view: Web page; click: Click; miniprogram: Mini Program
name Yes Menu name, with a length of up to 16 bytes. The maximum length of a sub-menu is 40 bytes.
key Required for click type Menu key, which is up to 128 bytes and used for pushing messages via the Message API.
url Required for view and miniprogram types The web page URL, which can be opened when a user taps the menu. It should not exceed 1024 bytes. When type is miniprogram, this URL will be opened in the older versions of the app that does not support Mini Program.
media_id Required for media_id and view_limited types The valid media_id returned by calling the New Permanent Media API
appid Required for miniprogram type Mini Program's appid
pagepath Required for miniprogram type Path to Mini Program screen
matchrule Yes Match rule for menu
tag_id No User tag ID, which can be obtained via the user tag management API
sex No Gender: Male (1); Female (2). No match is performed if this is left empty.
client_platform_type No Version of the WeChat app, specific to system model: iOS (1); Android (2); Others (3). No match is performed if this is left empty.
country No Country, which is the region set by the user in WeChat. See Region Information List for details.
province No Province, which is the region set by the user in WeChat. See Region Information List for details.
city No City, which is the region set by the user in WeChat. See Region Information List for details.
language No Language, which is set by the user in WeChat. See Language List for details: 1. Chinese (Simplified, PRC), "zh_CN"; 2. Chinese (Traditional, Taiwan), "zh_TW"; 3.Chinese (Traditional, Hong Kong S.A.R.), "zh_HK"; 4. English, "en"; 5. Indonesian, "id"; 6. Malay, "ms"; 7. Spanish, "es"; 8. Korean, "ko"; 9. Italian, "it"; 10. Japanese, "ja"; 11. Polish, "pl"; 12. Portuguese, "pt"; 13. Russion, "ru"; 14. Thai, "th"; 15. Vietnamese, "vi"; 16. Arabic, "ar"; 17. Hindi, "hi"; 18. Hebrew, "he"; 19. Turkish, "tr"; 20. German, "de"; 21. French, "fr"

"matchrule" contains six optional fields, but at least one match information must be specified. The region information is composed of country, province and city and verified from large to small according to the Region Information List. If the province is specified, the country is required and must be matched, but the city is optional. For example, "China Guangdong Guangzhou" and "China Guangdong" are valid region information. However, "China Guangzhou" is invalid, for the province is empty. Download the Region Information List.

Response

The returned JSON packet includes the following field for a successful request. If the request failed, the error code can be found in the API's error code description.

{"menuid":"208379533"}

Deleting Personalized Menu

HTTP request method: POST (HTTPS protocol should be used)

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

Request example

{"menuid":"208379533"}

"menuid" is the menu ID, which can be obtained via the Query Custom Menu API.

The returned JSON packet includes the following field for a successful request. If the request failed, the error code can be found in the API's error code description.

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

Testing Personalized Menu Match Result

HTTP request method: POST (HTTPS protocol should be used)

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

Request example

{"user_id":"weixin"}

"user_id" can be the OpenID or the WeChat ID of a follower.

Response This API returns the menu configuration, for example:

{
    "button": [
        {
            "type": "view", 
            "name": "tx", 
            "url": "http://www.qq.com/", 
            "sub_button": [ ]
        }, 
        {
            "type": "view", 
            "name": "tx", 
            "url": "http://www.qq.com/", 
            "sub_button": [ ]
        }, 
        {
            "type": "view", 
            "name": "tx", 
            "url": "http://www.qq.com/", 
            "sub_button": [ ]
        }
    ]
}

When an error occurs, the error code can be found in the API's error code description.

Query Personalized Menu

The Query Custom Menu API can be used to get the information of the default menu and all personalized menus. See the description of the Query Custom Menu API.

Deleting All Menus

The Delete Custom Menu API can be used to delete all custom menus (including the default menu and all personalized menus). See the description of the Delete Custom Menu API.