# Send customer service messages
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)
- Users send information
- 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)
- Follow Official Account
- 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 Name | type | Required to fill in | Introductions |
---|---|---|---|
touser | string | yes | User's OpenID |
msgtype | string | yes | Message type. Text represents a text message; Image represents picture message; Link means graphic link;Miniprogrampage represents a Weixin Mini Program card. |
text | object | no | Text message, required when msgtype = "text" |
image | object | no | Image message, required when msgtype = "image" |
voice | object | no | Voice message, required when msgtype = "voice" |
video | object | no | Required for video message, msgtype = "video" |
music | object | no | Music message, required when msgtype = "music" |
news | object | no | Graphic message (click to jump to the outside chain), msgtype = "news" required |
mpnews | object | no | 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) |
mpnewsarticle | object | no | Text message (click to jump to text message page), msgtype = "mpnewsarticle" is required, use the article_id obtained through the "publish" series interface |
msgmenu | object | no | Menu message, required when msgtype = "msgmenu" |
wxcard | object | no | Card coupon information, msgtype = "wxcard" required |
miniprogrampage | object | no | Weixin Mini Program message, msgtype = "miniprograpage" required |
customservice | object | no | Use some customer service account to send a message |
# Body.textObject Payload
Text message, required when msgtype = "text"
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
content | string | yes | Text 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 Name | type | Required to fill in | Introductions |
---|---|---|---|
media_id | string | yes | Media ID, obtained through the material upload interface. |
# Body.voiceObject Payload
Voice message, required when msgtype = "voice"
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
media_id | string | yes | Media ID, obtained through the material upload interface. |
# Body.videoObject Payload
Required for video message, msgtype = "video"
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
media_id | string | yes | Media ID, obtained through the material upload interface. |
thumb_media_id | string | yes | Thumbnail media ID, obtained through the material upload interface. |
title | string | no | Video title |
description | string | no | Video Description |
# Body.musicObject Payload
Music message, required when msgtype = "music"
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
title | string | yes | Music title |
description | string | yes | Music Description |
musicurl | string | yes | Music links |
hqmusicurl | string | no | High quality music links |
thumb_media_id | string | yes | Thumbnail Media ID |
# Body.newsObject Payload
Graphic message (click to jump to the outside chain), msgtype = "news" required
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
articles | objarray | yes | The 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 Name | type | Required to fill in | Introductions |
---|---|---|---|
media_id | string | yes | Material 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 Name | type | Required to fill in | Introductions |
---|---|---|---|
article_id | string | yes | Post Article ID |
# Body.msgmenuObject Payload
Menu message, required when msgtype = "msgmenu"
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
head_content | string | no | Menu Description |
list | objarray | yes | Menu Contents |
tail_content | string | no | Menu End |
# Body.wxcardObject Payload
Card coupon information, msgtype = "wxcard" required
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
card_id | string | yes | Voucher ID |
# Body.miniprogrampageObject Payload
Weixin Mini Program message, msgtype = "miniprograpage" required
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
title | string | yes | Weixin Mini Program Card Title |
appid | string | yes | Weixin Mini Program APPID |
pagepath | string | yes | Weixin Mini Program page path, aligned with apagejson, supports parameters such as pages / index / index?foo=bar |
thumb_media_id | string | yes | Weixin 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 Name | type | Required to fill in | Introductions |
---|---|---|---|
kf_account | string | yes | Customer Service Account |
# Body.news.articles(Array)Object Payload
The number of text message messages is limited to 1
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
title | string | yes | Message header |
description | string | yes | Message Description |
picurl | string | yes | Cover Image url |
url | string | yes | Jump url |
# Body.msgmenu.list(Array)Object Payload
Menu Contents
Parameter Name | type | Required to fill in | Introductions |
---|---|---|---|
id | string | yes | Menu values |
content | string | yes | Menu items |
# 3. Return Parameters
# Response Payload
Parameter Name | type | Introductions |
---|---|---|
errcode | number | Error code |
errmsg | string | Error 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"
}
# 5.6 Send an external link text message
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 code | Error Description | Solutions |
---|---|---|
-1 | system error | The system is busy, so the developer is asked to try again in a few minutes. |
40001 | invalid credential access_token isinvalid or not latest | AppSecret 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 |
40013 | invalid appid | Invalid AppID, please check the correctness of the AppID, avoid abnormal characters, pay attention to the case |
70000 | The message failed to be sent in order to protect the rights of minors |
# 7. Scope of application
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;