User Guide for Customer Service Messages
In order to enrich the service capabilities of Mini Programs and improve service quality, WeChat provides customer service messaging capabilities for Mini Programs, so that Mini Program users can communicate with Mini Program service providers conveniently and quickly.
Features
Users can use the Mini Program's customer service message function to communicate with the Mini Program's customer service personnel.
There are two customer service message session entries:
1. In the applet: the developer adds a customer service message button component in the applet , and the user can call up the customer service session page in the applet and send a message to the applet;
2. The used Mini Program customer service messages will be aggregated and displayed in the WeChat session "Mini Program Customer Service Message" box. Users can view historical customer service messages outside the Mini Program and send messages to the Mini Program.
Conditions for sending customer service messages: the Mini Program user initiates a customer service session in the Mini Program or the user sends a message to the Mini Program customer service. For the specific sending time, validity period and limit on the number of messages, please refer to the Conditions for Sending Customer Service Messages
Customer service message type: currently supports text, picture, and mini program card type messages.
In order to meet the needs of Mini Program developers as much as possible, Mini Programs can send customer service messages in the following three ways: 1. Call the API for sending customer service messages; 2. Use the customer service tools on the web; program.
Release condition statement
When the user interacts with the Mini Program customer service with a specific action (see the description below for the specific action list), the Mini Program can send a customer service message to the user.
The list of currently allowed actions is as follows. After different actions are triggered, the number of messages allowed to be sent and the time limit for sending them are different. When the number of sent threads reaches the upper limit, an error code will be returned.
| user action | Limit on the number of threads allowed | Release time limit |
|---|---|---|
| User sends message | 5 pieces | 48 hours |
The number of customer service messages that can be sent is not accumulated. The above user actions will trigger the update of the number of messages that can be sent and the time limit for delivery. The number of messages that can be sent will be updated to the maximum limit of the current number of messages that can be sent. The limit is also updated with the maximum valid time.
Call the customer service message interface to send customer service messages
When a user sends a message to the Mini Program customer service, the WeChat server will POST the message (or event) data package (JSON or XML format) to the URL filled in by the developer. After receiving the request, the developer can call the interface for asynchronous reply.
If the customer service message permission set of the Mini Program has been authorized to the third-party platform, all customer service messages will be pushed to the server of the third-party platform, and will no longer be pushed to the developer's server or to the web version of the customer service tool
Fill in the message push configuration
Log in to the applet, enable the message push function in "Settings-Development Settings-Message Push" and complete the configuration of relevant information (including server address, Token, and encryption method, etc.).
After enabling and setting the server configuration, messages sent by users and event pushes required by developers will be forwarded by WeChat to the developer URL.
interface call
Mini Program Customer Service Message API Documentation
Web-side customer service tools and mobile-side mini-program customer service tools
The applet can also directly use the WeChat applet customer service on the web page or the "Customer Service Assistant" applet on the mobile terminal to reply to customer service messages.
Small program code for customer service assistant
If the Mini Program does not enable message push, the message sent by the user will be forwarded to the WeChat Mini Program customer service on the web and the "Customer Service Assistant" on the mobile. ” to access and reply to the user.
If the customer service message permission set of the Mini Program has been authorized to the third-party platform, all customer service messages will be pushed to the server of the third-party platform, and will no longer be pushed to the server of the developer or to the customer service tool of the web version.
Note: The event "User enters session via customer service message button" will not be forwarded to the web customer service tool.
Bind customer service staff
Before using the web and mobile Mini Program customer service tools, the Mini Program administrator needs to complete the binding of customer service personnel in the Mini Program background. Currently, the Mini Program supports binding no more than 100 customer service personnel.
Instructions for using the "Customer Service Assistant" applet on the mobile terminal
login and access
The customer service staff of the bound Mini Program can search for "Customer Service Assistant" on WeChat or scan the QR code to log in to the "Customer Service Assistant" mini program, and select the corresponding Mini Program account. After logging in, you can see the users talking to the Mini Program. Optionally join the conversation.
Switch customer service status
Click on the online status, you can choose the online status of the customer service, the offline status of the customer service: After selecting the online status of the customer service, even if you exit the customer service applet, you can still receive the message reminder of the user consultation in the "Service Notification"; after selecting the offline status of the customer service, you will not be able to Receive customer service messages and message reminders.
Receive and send messages
After opening the "Customer Service Assistant" applet, enter the "Waiting to be Accessed List" to select user sessions to access; for sessions that have been accessed, customer service staff can chat with users within 48 hours. Currently, it supports sending text, pictures, A message of the Mini Program card type.
Instructions for using the WeChat mini-program customer service tool on the web
login and access
The customer service personnel of the Mini Program that has been bound can scan the QR code to log in to the WeChat Mini Program customer service on the web page , and select the corresponding Mini Program account. After logging in, you can see the users who are chatting with the Mini Program, and you can choose to access the chat.
Switch customer service status
Click online status, you can choose online status, offline status
receive message
Manual access: After the customer service personnel go online, they can manually access the user sessions to be replied in the "to be accessed" list.
Automatic access: When there are too many user sessions to be accessed, you can enable automatic access in Settings-Access and Reply.
Send a message
For the sessions that have been connected, the customer service staff can have a conversation with the user within 48 hours. Currently, it supports sending messages of text, pictures, and mini program cards.
Terms of Use
In addition to complying with the "WeChat Mini Program Platform Operating Specifications" , the use of Mini Program customer service messages must not violate the following rules, including but not limited to:
- It is not allowed to maliciously induce users to perform operations that may trigger the delivery of customer service messages, so as to achieve the purpose of delivering customer service messages to users
- Malicious harassment is not allowed, sending messages that are not related to the messages sent by users and cause harassment to users
- Malicious marketing is not allowed, and the distribution of content is suspected of false exaggeration and illegal marketing information
- It is not allowed to use customer service messages to send false, pornographic, violent and other information that violates national laws and regulations to users
Customer service message development document
customer service message
Use customer service messages on the page
buttonThe value of the component needs to open-typebe set to contact, when the user clicks, it will enter the customer service session. If the user clicks the message of the applet in the session, it will return to the applet. The developer can get bindcontactthe page of the message clicked by the user through the event callback Path pathand the corresponding parameters query. In addition, developers can transparently session-fromtransmit the session source to the customer service by setting .
sample code
<button open-type="contact" bindcontact="handleContact" session-from="sessionFrom"></button>Page({
handleContact (e) {
console.log(e.detail.path)
console.log(e.detail.query)
}
})
Return parameter description
| parameter | type | illustrate |
|---|---|---|
| path | String | The path specified by the applet message |
| query | Object | Query parameters specified by the applet message |
Background access message service
When a user sends a message to the Mini Program customer service, or enters a session, etc., the server URL filled in by the developer (if using cloud development, it is the configured cloud function) will get the messages and events pushed by the WeChat server, and the developer can Respond according to its own business logic. For access and usage methods, please refer to the message push .
Background access message error self-check
error performance
When the user sends a message, the system copy appears "The service provided by this applet has failed, please try again later".
Error reason
After the callback is configured in the applet, the message sent by the user will be pushed to the third-party server, and an error will be reported if the push fails.
Self-examination method
1. The applet enables message push (mini program background-development management-development settings-message push)
2. The mini program authorizes the "customer service authority" to the third-party platform (mini program background-settings-third-party settings-third-party platform authorization management)
*Special case
For Mini Programs that enable Cloud Functions but do not enable Cloud Hosting, messages sent by users will be pushed to Cloud Functions, and will not go to the Mini Program customer service system, nor will they call back to third-party servers or the server address of the Mini Program message push.
Forward the message to customer service
If the Mini Program is in development mode, when an ordinary WeChat user sends a message to the Mini Program customer service, the WeChat server will first POST the message to the url filled in by the developer. If you want to forward the message to the customer service system, you need Return a message whose MsgType is transfer_customer_service, and the WeChat server will forward the sent message to the customer service system after receiving the response.
After the user is connected by the customer service, before the customer service closes the session, and during the session, the messages sent by the user will be directly forwarded to the customer service system. When the session exceeds 30 minutes and the customer service is not closed, the WeChat server will automatically stop forwarding to the customer service, and resume sending the message to the url filled in by the developer.
When the user is in the waiting queue, the message sent by the user will still be pushed to the url filled in by the developer.
Special attention should be paid here that only messages sent by WeChat users are forwarded, and any other events should not be forwarded, otherwise the customer service will see some meaningless messages on the customer service system.
call description
<xml>
<ToUserName><![CDATA[touser]]></ToUserName>
<FromUserName><![CDATA[fromuser]]></FromUserName>
<CreateTime>1399197672</CreateTime>
<MsgType><![CDATA[transfer_customer_service]]></MsgType>
</xml>
Description of request parameters
| parameter | Is it necessary | describe |
|---|---|---|
| ToUserName | yes | Recipient's OpenID account |
| FromUserName | yes | Developer WeChat |
| CreateTime | yes | Message creation timestamp (integer) |
| MsgType | yes | transfer_customer_service |
Customer Service Management
Obtain basic customer service information
This interface provides a list of all customer service basic information under the applet.
call description
http request method: GET https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN
return instructions
Return data example (JSON return result when correct)
{
"kf_list" : [
{
"kf_account" : "",
"kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
"kf_id" : "1001",
"kf_nick" : "ntest1",
"kf_wx" : "kfwx1",
"kf_openid": "kfopenid1"
},
{
"kf_account" : "test1@test" ,
"kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
"kf_id" : "1002",
"kf_nick" : "ntest2",
"kf_wx" : "kfwx2",
"kf_openid": "kfopenid2"
},
{
"kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
"kf_id" : "1003",
"kf_nick" : "ntest3",
"kf_openid": "kfopenid3"
}
]
}
Return parameter description
| parameter | illustrate |
|---|---|
| kf_nick | Customer service nickname |
| kf_id | customer service number |
| kf_headimgurl | Customer service avatar |
| kf_wx | Customer service WeChat |
| kf_openid | customer service openid |
Get the list of online customer service
This interface provides access to all online customer service lists under the Mini Program.
call description
http request method: GET https://api.weixin.qq.com/cgi-bin/customservice/getonlinekflist?access_token=ACCESS_TOKEN
return instructions
Return parameter example
{
"kf_online_list" : [
{
"kf_account" : "test1@test" ,
"status" : 1,
"kf_id" : "1001",
"kf_openid": "kfopenid1"
},
{
"kf_account" : "",
"status" : 1,
"kf_id" : "1002",
"kf_openid": "kfopenid2"
}
]
}
Return parameter description
| parameter | illustrate |
|---|---|
| status | Customer service online status, 1: Web online |
| kf_id | customer service number |
| kf_openid | customer service openid |
Add customer service account
This interface adds the given customer service WeChat ID as a mini program customer service account.
call description
http request method: POST https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN
Example request parameters
{
"kf_wx" : "test1",
"business_id" : 1
}
Description of request parameters
| parameter | Is it necessary | illustrate |
|---|---|---|
| kf_wx | yes | Customer service WeChat |
return instructions
Return parameter example
// 返回数据示例（正确时的JSON返回结果）：
{
"errcode" : 0,
"errmsg" : "ok"
}
Delete customer service account
This interface deletes the Mini Program customer service account according to the given customer service number.
call description
http request method: GET https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN&kf_openid=KFOPENID
Description of request parameters
| parameter | Is it necessary | illustrate |
|---|---|---|
| kf_openid | yes | customer service openid |
Return parameter example
// 返回数据示例（正确时的JSON返回结果）：
{
"errcode" : 0,
"errmsg" : "ok"
}
Set up customer service administrator
This interface sets the customer service account corresponding to the customer service number of the Mini Program as the customer service administrator.
call description
http request method: GET https://api.weixin.qq.com/customservice/kfaccount/setadmin?access_token=ACCESS_TOKEN&kf_openid=KFOPENID
Description of request parameters
| parameter | Is it necessary | illustrate |
|---|---|---|
| kf_openid | yes | customer service openid |
return instructions
Return parameter example
// 返回数据示例（正确时的JSON返回结果）：
{
"errcode" : 0,
"errmsg" : "ok"
}
Cancel customer service administrator
This interface cancels the customer service administrator status of the corresponding customer service account according to the customer service number of the mini program.
call description
http request method: GET https://api.weixin.qq.com/customservice/kfaccount/canceladmin?access_token=ACCESS_TOKEN&kf_openid=KFOPENID
Description of request parameters
| parameter | Is it necessary | illustrate |
|---|---|---|
| kf_openid | yes | customer service openid |
return instructions
Return parameter example
// 返回数据示例（正确时的JSON返回结果）：
{
"errcode" : 0,
"errmsg" : "ok"
}
main return code
| return code | illustrate |
|---|---|
| 0 | success |
| 65400 | The API is unavailable, that is, the customer service function has not been activated/upgraded to a new version |
| 65401 | Invalid customer service account |
| 65402 | The customer service account has not been bound to the WeChat account and cannot be put into use |
| 65403 | Customer service nickname is invalid |
| 65404 | Customer service account is invalid |
| 65405 | The number of accounts has reached the upper limit and cannot be added |
| 65406 | Existing customer service account |
| 65407 | The invitee is already the customer service of this Mini Program |
| 65408 | This mini program already has an invitation to this WeChat |
| 65409 | invalid wechat |
| 65410 | The number of invited objects bound to the Mini Program customer service has reached the upper limit |
| 65411 | This account already has an invitation waiting to be confirmed, and cannot repeat the invitation |
| 65412 | This account has been bound to WeChat ID and cannot be invited |
| 65413 | There is no session information for the corresponding user |
| 65414 | The customer is being received by another customer service |
| 40003 | illegal openid |
| 40005 | unsupported media type |
| 40009 | Media file length is illegal |
Mini Program Customer Service Sub-merchant Capabilities Introduction and Development Documentation
Features
The customer service sub-merchant capability is the customer service capability support provided by the WeChat public platform for the integrated service platform mini-program. A Mini Program account can create multiple sub-merchant accounts for merchants on the platform, and after creation, a separate session of the sub-merchant will be invoked in the Mini Program customer service component. Multiple sub-merchant sessions are independent, which can provide users with a better customer service experience.
open range
对【电商平台】类目小程序开放。权限开通流程登录小程序管理后台，进入“设置-接口设置”，开通能力。子商户账号数量上限开通后，单个小程序账号可申请子商户账号上限为500个，如需申请上调，请以《小程序客服子商户数量上调申请_小程序名称》为主题，发送邮件至[email protected]，邮件内注明小程序账号appid、小程序名称、使用背景、需要申请的账号量、业务下已有产品(包括app/网站/公众号)信息。审核通过后可提高子商户数量上限。
开发文档
创建商户
接口调用请求说明
http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/register?access_token=ACCESS_TOKEN
JSON数据包如下
{
"account_name": "apple",
"nickname": "苹果",
"icon_media_id":"media_id"
"transfer_to_commkf": 0
}
返回报文示例
{ "business_id": 1 }
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| account_name | 是 | 创建商户时用到，一个account_name只能创建一次，account_name为6-30字符，必须为英文、数字、或者下划线，区分大小写。 |
| nickname | 是 | 商户昵称，会在客户端会话里展示，4-30字符(中文视为2字符)，由中文、英文、数字组成 |
| icon_media_id | 是 | 头像，图片类型，需要用临时素材接口得到:新增临时素材；为空则不更新头像 |
| transfer_to_commkf | 否 | 是否将消息转发到通用客服，0为不转发，1为转发 |
返回码说明
| 参数 | 说明 |
|---|---|
| 45070 | account_name对应账号已经被创建(一个account_name对应一个business_id) |
| 45077 | 子商户数量已达到上限 |
| 45078 | 昵称不合法，请检查是否满足nickname规则 |
| 45079 | 昵称含有违规词汇 |
| 40007 | icon_media_id不是合法的media_id |
| 40004 | icon_media_id类型不对，应该为图片类型 |
| 45091 | account_name不合法，请检查是否满足account_name规则 |
更新商户信息
接口调用请求说明
http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/update?access_token=ACCESS_TOKEN
JSON数据包如下
{
"business_id": 1,
"nickname": "苹果",
"icon_media_id":""
}
返回报文示例
{
"errcode": 0,
"errmsg": "ok"
}
说明
- nickname为空则不更新昵称
- icon_media_id为空则不更新头像
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| business_id | 是 | 创建商户时得到的商户id |
| nickname | 否 | 商户昵称，会在客户端会话里展示，4-30字符(中文视为2字符)，由中文、英文、数字组成;为空则不更新昵称 |
| icon_media_id | 否 | 头像，图片类型，需要用临时素材接口得到:新增临时素材；为空则不更新头像 |
返回码说明
| 参数 | 说明 |
|---|---|
| 45071 | business_id对应的商户不存在 |
| 45077 | 子商户数量已达到上限 |
| 45078 | 昵称不合法，请检查是否满足nickname规则 |
| 45079 | 昵称含有违规词汇 |
| 40007 | icon_media_id不是合法的media_id |
| 40004 | icon_media_id类型不对，应该为图片类型 |
拉取单个商户信息
接口调用请求说明
http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/get?access_token=ACCESS_TOKEN
JSON数据包如下
{
"business_id": 1
}
或
{
"account_name": "apple"
}
返回报文示例
{
"business_info":
{
"business_id": 1,
"account_name": "apple",
"nickname":"苹果",
"icon_url":"icon_url"
}
}
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| business_id | 否 | 创建商户时得到的商户id,与account_name选填一个 |
| account_name | 否 | 创建商户时用到的account_name,与business_id选填一个 |
返回码说明
| 参数 | 说明 |
|---|---|
| 45071 | business_id/account_name对应的商户不存在 |
拉取多个商户信息
接口调用请求说明
http请求方式: POST https://api.weixin.qq.com/cgi-bin/business/list?access_token=ACCESS_TOKEN
JSON数据包如下
{
"offset": 0,
"count": 100
}
返回报文示例
{
"list": [
{
"business_id": 1,
"account_name": "apple",
"nickname":"苹果",
"icon_url":"icon_url"
},
{
"business_id": 2,
"account_name": "apple",
"nickname":"苹果",
"icon_url":"icon_url"
}
]
}
说明: 某一次请求的返回的数据量小于count数，说明请求的数据已经到了末端
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| offset | yes | Used for page pull, starting from 0 |
| count | yes | The number of merchants pulled at one time, up to 200 |
Receive message push
For details, please refer to Customer Service Messages to receive messages and events. When pushing, a parameter BusinessId will be added, indicating that the message comes from the session of the sub-merchant. Take sending a text message as an example:
JSON format example
{
"ToUserName": "toUser",
"FromUserName": "fromUser",
"CreateTime": 1482048670,
"MsgType": "text",
"Content": "this is a test",
"MsgId": 1234567890123456,
"BusinessId": 1
}
XML format example
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>1482048670</CreateTime>
<MsgType><![CDATA[text]]></MsgType>
<Content><![CDATA[this is a test]]></Content>
<MsgId>1234567890123456</MsgId>
<BusinessId>1</BusinessId>
</xml>
Send customer service message
Interface call request description
http request method: POST https://api.weixin.qq.com/cgi-bin/message/custom/business/send?access_token=ACCESS_TOKEN
JSON data packet
Except that the request url is different, postdata can directly refer to the original customer service message JSON data packet, and add the parameter businessid on this basis. To send
Send a text message as an example:
{
"touser":"OPENID",
"businessid":1,
"msgtype":"text",
"text":
{
"content":"Hello World"
}
}
Customer service input status
Interface call request description
http request method: POST https://api.weixin.qq.com/cgi-bin/message/custom/business/typing?access_token=ACCESS_TOKEN
JSON data packet
In addition to the different request url, postdata can directly refer to the JSON data packet of the original customer service input status interface , and add the parameter businessid on this basis, the example is as follows:
{
"businessid":1,
"touser":"OPENID",
"command":"Typing"
}
The applet component initiates a sub-merchant customer service session
button adds an attribute business-id, indicating the sub-merchant ID.