To help Official Account operators run business flexibly, the Weixin 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 Weixin app)
5. Language (set by the user in the Weixin app)
Description of personalized menu APIs:
1. Personalized menu is only supported as of Weixin 6.2.2 for iOS and Weixin 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
3. Test personalized menu match result
# 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 Weixin 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 Weixin. See Region Information List for details. |
| province | No | Province, which is the region set by the user in Weixin. See Region Information List for details. |
| city | No | City, which is the region set by the user in Weixin. See Region Information List for details. |
| language | No | Language, which is set by the user in Weixin. 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 Weixin 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.