# Create a custom menu

Debugging Tools

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 NametypeRequired to fill inIntroductions
access_tokenstringyesInterface invocation credentials, using access_token , authorizer_access_token

# Request BodyRequest Payload

Parameter NametypeRequired to fill inIntroductions
buttonobjarrayyesAn array of primary menu structures

# Body.button(Array)Object Payload

An array of primary menu structures

Parameter NametypeRequired to fill inExampleIntroductionsto enumerate
typestringnoclickResponse 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
namestringyesSongs of the dayMenu title, no more than 16 bytes, submenu no more than 60 bytes-
keystringno-The menu KEY value, used for message interface push, does not exceed 128 bytes. Click, etc. Click types must be.-
urlstringno-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_idstringno-The valid media_id returned by calling the new permanent material interface. The media_id type and the view_limited type must-
appidstringno-Weixin Mini Program of AppID (only Official Account can be configured), the miniprogram type must-
pagepathstringno-The page path of Weixin Mini Program, the miniprogram type must-
article_idstringno-The legal article_id, article_id type, and article_view_limited type obtained after publication must be-
sub_buttonobjarrayno-Array of secondary menu structures-

# Body.button(Array).sub_buttonObject Payload

Array of secondary menu structures

Parameter NametypeRequired to fill inExampleIntroductions
typestringyesclickThe response action type of the menu (type of the same level menu)
namestringyesSongs of the dayMenu title, no more than 16 bytes, submenu no more than 60 bytes
keystringno-The menu KEY value, used for message interface push, does not exceed 128 bytes. Click, etc. Click types must be.
urlstringno-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_idstringno-The valid media_id returned by calling the new permanent material interface. The media_id type and the view_limited type must
appidstringno-Weixin Mini Program of AppID (only Official Account can be configured), the miniprogram type must
pagepathstringno-The page path of Weixin Mini Program, the miniprogram type must
article_idstringno-The legal article_id, article_id type, and article_view_limited type obtained after publication must be

# 3. Return Parameters

# Response Payload

Parameter NametypeIntroductions
errcodenumberError code
errmsgstringError Description

# 4. Note

  1. 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.
  2. 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 "..."
  3. 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:

  1. 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;
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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.
  10. 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
  11. 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 codeError DescriptionSolutions
0Ok or in a normal stateOK means to go from abnormal to normal in a normal state
40018invalid button name sizeUnlawful button name length

# 7. Scope of application

How this interface can be invoked under different account types:
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;