# Create a custom menu
Interface should be called on the server side, not in the front end (Weixin Mini Program, web pages, APP, etc.) directly called, specific reference interface call guide
Interface Name: createCustomMenu
This interface is used to create custom menus for Official Account / Service Account.
# 1. How to call
# HTTPS calls
POST https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
# Cloud Calls
Call method: officialAccount.menu.create
The input and exit parameters are the same as the HTTPS call, which can be called in the cloud call documentation
# Third party invocation
This interface supports Third Party Platform generation business call.
The permission set id to which the interface belongs is: 15
When a service provider is authorized by one of the permissions set, it can call on behalf of the merchant by using authorizer_access_token , which can be viewed in the third-party call documentation.
# 2. Request parameters
# Query parametersQuery String parameters
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
access_token | string | yes | Interface invocation credentials, using access_token , authorizer_access_token |
# Request BodyRequest Payload
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
button | objarray | yes | An array of primary menu structures |
# Body.button(Array)Object Payload
An array of primary menu structures
Parameter Name | type | Required to fill in | Example | Introductions | to enumerate |
---|---|---|---|---|---|
type | string | no | click | Response action type of menu (exclusive of sub_button) | click view scancode_push scancode_waitmsg pic_sysphoto pic_photo_or_album pic_weixin location_select media_id article_id article_view_limited |
name | string | yes | Songs of the day | Menu title, no more than 16 bytes, submenu no more than 60 bytes | - |
key | string | no | - | The menu KEY value, used for message interface push, does not exceed 128 bytes. Click, etc. Click types must be. | - |
url | string | no | - | Web links, which users can open by clicking on a menu, are no more than 1024 bytes.When type is miniprogram, older versions of the Portals that do not support Weixin Mini Program will open this url.View, miniprogram types are required. | - |
media_id | string | no | - | The valid media_id returned by calling the new permanent material interface. The media_id type and the view_limited type must | - |
appid | string | no | - | Weixin Mini Program of AppID (only Official Account can be configured), the miniprogram type must | - |
pagepath | string | no | - | The page path of Weixin Mini Program, the miniprogram type must | - |
article_id | string | no | - | The legal article_id, article_id type, and article_view_limited type obtained after publication must be | - |
sub_button | objarray | no | - | Array of secondary menu structures | - |
# Body.button(Array).sub_buttonObject Payload
Array of secondary menu structures
Parameter Name | type | Required to fill in | Example | Introductions |
---|---|---|---|---|
type | string | yes | click | The response action type of the menu (type of the same level menu) |
name | string | yes | Songs of the day | Menu title, no more than 16 bytes, submenu no more than 60 bytes |
key | string | no | - | The menu KEY value, used for message interface push, does not exceed 128 bytes. Click, etc. Click types must be. |
url | string | no | - | Web links, which users can open by clicking on a menu, are no more than 1024 bytes.When type is miniprogram, older versions of the Portals that do not support Weixin Mini Program will open this url.View, miniprogram types are required. |
media_id | string | no | - | The valid media_id returned by calling the new permanent material interface. The media_id type and the view_limited type must |
appid | string | no | - | Weixin Mini Program of AppID (only Official Account can be configured), the miniprogram type must |
pagepath | string | no | - | The page path of Weixin Mini Program, the miniprogram type must |
article_id | string | no | - | The legal article_id, article_id type, and article_view_limited type obtained after publication must be |
# 3. Return Parameters
# Response Payload
Parameter Name | type | Introductions |
---|---|---|
errcode | number | Error code |
errmsg | string | Error Description |
# 4. Note
- A custom menu can consist of up to 3 tier 1 menus, and each tier 1 can consist of as many as 5 tier 2 menus.
- The first menu has a maximum of 4 Chinese characters and the second menu has maximum of 8 Chinese characters. The additional portion will be replaced by "..."
- After creating a custom menu, the menu's refresh strategy is to refresh the menu when the user entersOfficial Account / Service Account session page or Official Account / service profile page, if the last request to pull the menu was 5 minutes ago, will pull the menu, if the menu has been updated, will refresh the client menu.When testing, you can try to unfollow the Official Account message template / service number, then you can see the effect of the creation.
A custom menu interface can implement many types of buttons, as follows:
- Click: Click to push event When the user clicks the click type button, WeChat the server pushes the message type as event structure to the developer via the message interface (refer to the message interface guide),And with the key value filled in the button, the developer can interact with the user through the self-defined key value;
- View: Jump URL When the user clicks the view type button, WeChat the client will open the web page URL filled out by the developer in the button, which can be combined with the web page authorizing user basic information interface to obtain user basic info.
- When the user clicks the button, the WeChat User will activate the scan tool.After completing the scan operation, the scan result is displayed (if it is URL, the URL will be entered), and the results of the scan will be sent to the developer, who can send a message.
- Scan code_waitmsg: scan code push event and pop up "message receiving" prompt box after the user clicks the button,WeChat The client will call up the scanning tool, when the scanning operation is complete, transmit the results of the scanning to the developer, and close the scanning tools, then pop up the "Message Received" prompt box, and may receive a message from the developer.
- Pic_sysphoto: After the user clicks the button,WeChat The client will turn on the system camera and, after taking a photo, send the photo to the developer and push the event to the developer, while removing the system camera, and may receive a message from the developer.
- pic_photo_or_album: pop-up photo or album post After the user clicks the button, WeChat the client pops up a selector for the user to choose "photo" or "select from the phone album."Once the user chooses, the other two processes are followed.
- Pic_weixin: The WeChat Album Organizer pops up when the user clicks the button,The WeChat client will activate the WeChat photo album, after completing the selection operation, send the selected photo to the developer's server, push the event to the developer, and close the album, after which it may receive a message from the developer.
- Location_select: When the user clicks the button, the WeChat Home will activate the location selection tool.Once you have completed the selection, send the selected geographical location to the developer's server, and close the location selection tool. You may then receive a message from the developer.
- Media_id: Send messages (other than text messages) When a user clicks the media_id type button, the WeChat server sends to the user the content corresponding to the developer's permanent material id, which can be a picture, audio, or video.Note: The Persistent Asset ID must be a valid ID obtained after uploading to the Asset Management / Add Persistent Asset interface.
- Article_id: When the user clicks the article_id type button, the WeChat Client will send a graphic message that the developer filled in the button in the form of a card
- Article_view_limited: similar to view_limited, but using article_id instead of media_id
Note: After the completion of the draft interface grayscale, the media_id and view_limited of graphic and text information types will no longer be supported. If necessary, please use article_id and article_view_limited instead
Please note that all events from 3 to 8 are only supported by WeChat WeChat users of iPhone 5.4.1 and Android 5.4. Older WeChat users will not respond when they click, and developers will not receive event pushes normally. 9-11, is dedicated to Third Party Platform's non-WeChat authentication (specifically, Official Account prepared event types that have not passed the qualification certification), they are not pushed by events, and their capabilities are relatively limited, and other types of official accounts/Service Account do not need to be used.
# 5. Code examples
# 5.1 Click and view
Example Requests
{
"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"
}]
}]
}
Return an example
{
"errcode": 0,
"errmsg": "ok"
}
# 5.2 Other new button types
Example Requests
{
"button": [
{
"name": "扫码",
"sub_button": [
{
"type": "scancode_waitmsg",
"name": "扫码带提示",
"key": "rselfmenu_0_0",
"sub_button": [ ]
},
{
"type": "scancode_push",
"name": "扫码推事件",
"key": "rselfmenu_0_1",
"sub_button": [ ]
}
]
},
{
"name": "发图",
"sub_button": [
{
"type": "pic_sysphoto",
"name": "系统拍照发图",
"key": "rselfmenu_1_0",
"sub_button": [ ]
},
{
"type": "pic_photo_or_album",
"name": "拍照或者相册发图",
"key": "rselfmenu_1_1",
"sub_button": [ ]
},
{
"type": "pic_weixin",
"name": "微信相册发图",
"key": "rselfmenu_1_2",
"sub_button": [ ]
}
]
},
{
"name": "发送位置",
"type": "location_select",
"key": "rselfmenu_2_0"
},
{
"type": "media_id",
"name": "图片",
"media_id": "MEDIA_ID1"
},
{
"type": "view_limited",
"name": "图文消息",
"media_id": "MEDIA_ID2"
},
{
"type": "article_id",
"name": "发布后的图文消息",
"article_id": "ARTICLE_ID1"
},
{
"type": "article_view_limited",
"name": "发布后的图文消息",
"article_id": "ARTICLE_ID2"
}
]
}
Return an example
{
"errcode": 0,
"errmsg": "ok"
}
# 6. Error code
The following is a list of error codes for this interface, other error codes can refer to General error codes
Error code | Error Description | Solutions |
---|---|---|
0 | Ok or in a normal state | OK means to go from abnormal to normal in a normal state |
40018 | invalid button name size | Unlawful button name length |
# 7. Scope of application
Official Account | Service Account |
---|---|
Certification only | ✔ |
- Authentication only: means that only authenticated accounts are allowed to be invoked by the enterprise entity, and accounts that are not authenticated or do not support authentication cannot be invoked.
- ✔: The account can call this interface
- Other account types that are not expressly stated may not be called on this interface without special instructions;