# Send customer service messages

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: sendCustomMessage

This interface is used to send many types of customer service messages and is mainly used in situations where there is manual message processing.

When an interaction between a user and an app creates a specific action, WeChat pushes the message data to the developer, who can call the customer service interface for a period of time (currently 48 hours) to send a message to the average user by POSTing a JSON packet.

The list of currently allowed actions is as follows (the public platform will update the list based on operational conditions, and the customer service interfaces allowed when different actions are triggered)

  1. Users send information
  2. Click on custom menus (Only three menu types - click push events, scan push events, and scan push events that pop up the "Message Received" prompt box - trigger the customer service interface)
  3. Follow Official Account
  4. Scan QR code

Rules for customer service message delivery for each scenario:

scene Amount of withdrawal Amount validity period
Users send messages 5 Rules 48 hours
Click on the custom menu 3 Rules 1 minute
Follow Official Account 3 Rules 1 minute
Scan QR code 3 Rules 1 minute

# 1. How to call

# HTTPS calls

POST https://api.weixin.qq.com/cgi-bin/message/custom/send

# Cloud Calls

  • This interface does not support cloud calls

# Third party invocation

  • This interface supports Third Party Platform generation business call.

  • The permissions set to which the interface belongs are: 1, 6, 19, 100-101

  • 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

nothing

# Request BodyRequest Payload

Parameter NametypeRequired to fill inIntroductions
touserstringyesUser's OpenID
msgtypestringyesMessage type. Text represents a text message; Image represents picture message; Link means graphic link;Miniprogrampage represents a Weixin Mini Program card.
textobjectnoText message, required when msgtype = "text"
imageobjectnoImage message, required when msgtype = "image"
voiceobjectnoVoice message, required when msgtype = "voice"
videoobjectnoRequired for video message, msgtype = "video"
musicobjectnoMusic message, required when msgtype = "music"
newsobjectnoGraphic message (click to jump to the outside chain), msgtype = "news" required
mpnewsobjectnoGraphic messages (click to jump to the Graphic Message page) must be filled in when msgtype = "mpnews." The number of graphic message entries is limited to 1. Note that if the number of graphics exceeds 1, error code 45008 will be returned.(This type is no longer supported after the graying of the draft is completed)
mpnewsarticleobjectnoText message (click to jump to text message page), msgtype = "mpnewsarticle" is required, use the article_id obtained through the "publish" series interface
msgmenuobjectnoMenu message, required when msgtype = "msgmenu"
wxcardobjectnoCard coupon information, msgtype = "wxcard" required
miniprogrampageobjectnoWeixin Mini Program message, msgtype = "miniprograpage" required
customserviceobjectnoUse some customer service account to send a message

# Body.textObject Payload

Text message, required when msgtype = "text"

Parameter NametypeRequired to fill inIntroductions
contentstringyesText content, supports inserting text chains that jump Weixin Mini Program,

For example "text content click jump Weixin Mini Program "

Dxplaination: 1. data-miniprogram- AppID item, fill in Weixin Mini Program appid, indicating that the link jump Mini Program; 2. Data-miniprogram-path item, fill in the Mini Program path, the path is consistent with Apagejson, can take parameters; 3. For the guest version that does not support the data-miniprogram-appid entry, if there is a herf entry, the web link in the jump href is still maintained; 4.The data-miniprogram-appid Mini Program must be bound to Official Account.

# Body.imageObject Payload

Image message, required when msgtype = "image"

Parameter NametypeRequired to fill inIntroductions
media_idstringyesMedia ID, obtained through the material upload interface.

# Body.voiceObject Payload

Voice message, required when msgtype = "voice"

Parameter NametypeRequired to fill inIntroductions
media_idstringyesMedia ID, obtained through the material upload interface.

# Body.videoObject Payload

Required for video message, msgtype = "video"

Parameter NametypeRequired to fill inIntroductions
media_idstringyesMedia ID, obtained through the material upload interface.
thumb_media_idstringyesThumbnail media ID, obtained through the material upload interface.
titlestringnoVideo title
descriptionstringnoVideo Description

# Body.musicObject Payload

Music message, required when msgtype = "music"

Parameter NametypeRequired to fill inIntroductions
titlestringyesMusic title
descriptionstringyesMusic Description
musicurlstringyesMusic links
hqmusicurlstringnoHigh quality music links
thumb_media_idstringyesThumbnail Media ID

# Body.newsObject Payload

Graphic message (click to jump to the outside chain), msgtype = "news" required

Parameter NametypeRequired to fill inIntroductions
articlesobjarrayyesThe number of text message messages is limited to 1

# Body.mpnewsObject Payload

Graphic messages (click to jump to the Graphic Message page) must be filled in when msgtype = "mpnews." The number of graphic message entries is limited to 1. Note that if the number of graphics exceeds 1, error code 45008 will be returned.(This type is no longer supported after the graying of the draft is completed)

Parameter NametypeRequired to fill inIntroductions
media_idstringyesMaterial ID, obtained through the material upload interface.

# Body.mpnewsarticleObject Payload

Text message (click to jump to text message page), msgtype = "mpnewsarticle" is required, use the article_id obtained through the "publish" series interface

Parameter NametypeRequired to fill inIntroductions
article_idstringyesPost Article ID

# Body.msgmenuObject Payload

Menu message, required when msgtype = "msgmenu"

Parameter NametypeRequired to fill inIntroductions
head_contentstringnoMenu Description
listobjarrayyesMenu Contents
tail_contentstringnoMenu End

# Body.wxcardObject Payload

Card coupon information, msgtype = "wxcard" required

Parameter NametypeRequired to fill inIntroductions
card_idstringyesVoucher ID

# Body.miniprogrampageObject Payload

Weixin Mini Program message, msgtype = "miniprograpage" required

Parameter NametypeRequired to fill inIntroductions
titlestringyesWeixin Mini Program Card Title
appidstringyes Weixin Mini Program APPID
pagepathstringyesWeixin Mini Program page path, aligned with apagejson, supports parameters such as pages / index / index?foo=bar
thumb_media_idstringyesWeixin Mini Program The cover of the message card, the media_id of the image type, obtained by uploading the picture file of the material, the recommended size is 520 * 416

# Body.customserviceObject Payload

Use some customer service account to send a message

Parameter NametypeRequired to fill inIntroductions
kf_accountstringyesCustomer Service Account

# Body.news.articles(Array)Object Payload

The number of text message messages is limited to 1

Parameter NametypeRequired to fill inIntroductions
titlestringyesMessage header
descriptionstringyesMessage Description
picurlstringyesCover Image url
urlstringyesJump url

# Body.msgmenu.list(Array)Object Payload

Menu Contents

Parameter NametypeRequired to fill inIntroductions
idstringyesMenu values
contentstringyesMenu items

# 3. Return Parameters

# Response Payload

Parameter NametypeIntroductions
errcodenumberError code
errmsgstringError Description

# 4. Note

  • When sending text messages, support for adding text links that jump Weixin Mini Program.
  • Data-miniprogram- AppID, fill in Weixin Mini Program appid, indicating that the link jump Mini Program
  • Data-miniprogram-path item, fill in Weixin Mini Program path, path and apagejson consistent, with parameters;
  • For guest versions (below 6.5.16) that do not support the data-miniprogram- AppID entry, if there is a herf entry, the link in the jump href is still maintained;
  • Weixin Mini Program A text message for a headband Mini Program text chain, data-miniprogram- AppID must be the appid of the Mini Program

# 5. Code examples

# 5.1 Send a text message

Example Requests

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":`文本内容<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>`
    },
    "customservice":{
         "kf_account": "test1@kftest"
    }
}

Return an example

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

# 5.2 Send a picture message

Example Requests

{
    "touser":"OPENID",
    "msgtype":"image",
    "image":
    {
      "media_id":"MEDIA_ID"
    }
}

Return an example

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

# 5.3 Send voice messages

Example Requests

{
    "touser":"OPENID",
    "msgtype":"voice",
    "voice":
    {
      "media_id":"MEDIA_ID"
    }
}

Return an example

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

# 5.4 Send a video message

Example Requests

{
    "touser":"OPENID",
    "msgtype":"video",
    "video":
    {
      "media_id":"MEDIA_ID",
      "thumb_media_id":"MEDIA_ID",
      "title":"TITLE",
      "description":"DESCRIPTION"
    }
}

Return an example

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

# 5.5 Send music messages

Example Requests

{
    "touser":"OPENID",
    "msgtype":"music",
    "music":
    {
      "title":"MUSIC_TITLE",
      "description":"MUSIC_DESCRIPTION",
      "musicurl":"MUSIC_URL",
      "hqmusicurl":"HQ_MUSIC_URL",
      "thumb_media_id":"THUMB_MEDIA_ID" 
    }
}

Return an example

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

Example Requests

{
    "touser":"OPENID",
    "msgtype":"news",
    "news":{
        "articles": [
         {
             "title":"Happy Day",
             "description":"Is Really A Happy Day",
             "url":"URL",
             "picurl":"PIC_URL"
         }
         ]
    }
}

Return an example

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

# 5.7 Send Official Account graphic message (deprecated)

Example Requests

{
    "touser":"OPENID",
    "msgtype":"mpnews",
    "mpnews":
    {
         "media_id":"MEDIA_ID"
    }
}

Return an example

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

# 5.8 Send Official Account graphic message

Example Requests

{
    "touser":"OPENID",
    "msgtype":"mpnewsarticle",
    "mpnewsarticle": {
         "article_id":"ARTICLE_ID"
    }
}

Return an example

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

# 5.9 Send Menu Messages

Example Requests

{
  "touser": "OPENID",
  "msgtype": "msgmenu",
  "msgmenu": {
    "head_content": "您对本次服务是否满意呢? ",
    "list": [
      {
        "id": "101",
        "content": "满意"
      },
      {
        "id": "102",
        "content": "不满意"
      }
    ],
    "tail_content": "欢迎再次光临"
  }
}

Return an example

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

# 5.10 Send a coupon message

Example Requests

{
  "touser":"OPENID", 
  "msgtype":"wxcard",
  "wxcard":
  {              
   "card_id":"123dsdajkasd231jhksad"        
   }
}

Return an example

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

# 5.11 Send Weixin Mini Program message

Example Requests

{
    "touser":"OPENID",
    "msgtype":"miniprogrampage",
    "miniprogrampage":
    {
        "title":"title",
        "appid":"appid",
        "pagepath":"pagepath",
        "thumb_media_id":"thumb_media_id"
    }
}

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
-1system errorThe system is busy, so the developer is asked to try again in a few minutes.
40001invalid credential  access_token isinvalid or not latestAppSecret error while getting access_token, or access_token is invalid.Developers should check that AppSecret is correct, or that they are calling interfaces for the appropriate Official Account
40013invalid appidInvalid AppID, please check the correctness of the AppID, avoid abnormal characters, pay attention to the case
70000The message failed to be sent in order to protect the rights of minors

# 7. Scope of application

How this interface can be invoked under different account types:
Weixin Mini Program Official Account Service Account MiniGame
Certification only Certification only
  • ✔: The account can call this interface
  • 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.
  • Other account types that are not expressly stated may not be called on this interface without special instructions;