A custom menu enriches your Official Account interface and allows users to understand the features of Official Accounts better and faster. After the custom menu is enabled, the interface of an Official Account looks like this:
Notes:
1. A custom menu contains up to 3 primary menus, and each primary menu contains up to 5 secondary menus.
2. A primary/secondary menu displays a maximum of 4/7 Chinese characters, respectively. If this limit is exceeded, extra characters will be replaced with "...".
3. After a custom menu is created, 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.
The "Custom Menu" API can be used to create the following buttons:
1. click: Pushes an event once tapped. After a user taps the click button, the Weixin server pushes a structure with event as the message type via the message API (see Message API documentation) to the developer, along with a key value entered in the button by the developer. The developer can interact with users via the custom key.
2. view: Redirects to URL. After a user taps the view button, the Weixin app opens the website URL entered in the button by the developer to access the API for getting the user's basic information via webpage authorization to get the user's basic information.
3. scancode_push: Pushes an event when a code is scanned. After a user taps this button, the Weixin app calls the "Scan" tool, displays the scanning result after a QR code is scanned (if the result is an URL, it will be opened), and returns the result to the developer to send message.
4. scancode_waitmsg: Pushes an event and displays "Receiving message" when a code is scanned. After a user taps this button, the Weixin app calls the "Scan" tool, returns the scanning result to the developer, then hide the "Scan" tool, displays the "Receiving message" prompt box, and then may receive the message sent from the developer.
5. pic_sysphoto: Sends an image by taking a photo with the system camera. After a user taps this button, the Weixin app calls the system camera to take a photo, then sends the photo and pushes an event to the developer, hides the camera, and then may receive the message sent from the developer.
6. pic_photo_or_album: Sends an image by taking a photo with the system camera or selecting from the Weixin album. After a user taps this button, a selector pops up in the Weixin app for the user to select "Camera" or "Album". After selection, the user will proceed with the respective process.
7. pic_weixin: Sends an image by selecting from the Weixin album. After a user taps this button, the Weixin app calls the Weixin album, then sends the selected photo and pushes an event to the developer, hides the album, and then may receive the message sent from the developer.
8. location_select: Displays the geographic location selector. After a user taps this button, the Weixin app calls the geographic location selector, then sends the selected geographic location to the developer, hides the selector, and then may receive the message sent from the developer.
9. media_id: Sends a message (excluding articles). After a user taps the media_id button, the Weixin server sends the media corresponding to the permanent media id entered by the developer to the user. The type of permanent media includes image, audio, video, and article. Note: The permanent media id must be a valid id obtained after the media is uploaded via the "Media Asset Management/New Permanent Media" API.
10. view_limited: Redirects to an article URL. After a user taps the view_limited button, the Weixin server opens the article URL corresponding to the permanent media id entered in the button by the developer. The type of permanent media can only be article. Note that the permanent media id must be a valid id obtained after the media is uploaded via the "Media Asset Management/New Permanent Media" API.
Note: Events 3 to 8 are supported as of Weixin 5.4.1 for iOS and Weixin 5.4 for Android. In older versions, no response is returned and no event will be pushed to the developer after the user taps the appropriate button. Events 9 and 10 are specific to Subscription Accounts whose identities are not verified via Weixin Verification on the third-party platforms, which are not pushed with limited capabilities and are not applicable to other types of Official Accounts.
API Request Format
HTTP request method: POST (HTTPS protocol should be used) https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
Example of request for click and view
{
"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"
}]
}]
}
Example of request for new button type
{
"button": [
{
"name": "Scan code",
"sub_button": [
{
"type": "scancode_waitmsg",
"name": "Scan code and notify",
"key": "rselfmenu_0_0",
"sub_button": [ ]
},
{
"type": "scancode_push",
"name": "Scan code and push event",
"key": "rselfmenu_0_1",
"sub_button": [ ]
}
]
},
{
"name": "Send image",
"sub_button": [
{
"type": "pic_sysphoto",
"name": "Send image by taking photo using system camera",
"key": "rselfmenu_1_0",
"sub_button": [ ]
},
{
"type": "pic_photo_or_album",
"name": "Send image by taking photo or selecting from album",
"key": "rselfmenu_1_1",
"sub_button": [ ]
},
{
"type": "pic_weixin",
"name": "Send image from Weixin album",
"key": "rselfmenu_1_2",
"sub_button": [ ]
}
]
},
{
"name": "Send location",
"type": "location_select",
"key": "rselfmenu_2_0"
},
{
"type": "media_id",
"name": "Image",
"media_id": "MEDIA_ID1"
},
{
"type": "view_limited",
"name": "Article",
"media_id": "MEDIA_ID2"
}
]
}
Parameters
| Parameter | Required | Description |
|---|---|---|
| button | Yes | The array of primary menus. The number of menus should be between 1 and 3. |
| sub_button | No | 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 60 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 | The Mini Program's appid (only supported for verified Official Accounts) |
| pagepath | Required for miniprogram type | Path to Mini Program screen |
Response
The returned JSON packet for a successful request:
{"errcode":0,"errmsg":"ok"}
The returned JSON packet for a failed request (this is an example of invalid length of menu name):
{"errcode":40018,"errmsg":"invalid button name size"}