When an interaction of special action (see the following list for specific actions) is generated between a user and an Official Account, Weixin sends the message data to the developer, and then the developer sends messages to the user by calling the Customer Service API within a period of time (48 hours) to POST a JSON data packet. This API is mainly used for customer service and other features with manual message processing, so that the developer can provide better services for users.

The allowed actions are listed below (The Official Accounts Platform updates the list based on the operating status. The max number of messages sent via the Customer Service API varies depending on different actions triggered. When the max number is reached, an error code is returned. For details, see the error code description):

1. Send a message
2. Tap the custom menu (Only 3 menu types - Push an event when the menu is tapped, Push an event when a code is scanned, and Push an event and display "Receiving message" when a code is scanned - can trigger the Customer Service API)
3. Follow an Official Account
4. Scan a QR code
5. Pay successfully
6. Raise a dispute

To help Official Accounts serve different user groups using different customer service identities, we upgrade the Customer Service API for developers to manage customer service accounts and set profile photo and alias of customer service accounts. This capability is open to all Official Accounts with access to the Customer Service API.

In addition, developers should know that the media_id of permanent assets in Media Asset Management can be used where media_id is required in the API.

Contents

1 Customer Service Account Management

1.1 Adding Customer Service Accounts

1.2 Modifying Customer Service Accounts

1.3 Deleting Customer Service Accounts

1.4 Setting Profile Photo of Customer Service Accounts

1.5 Getting All Customer Service Accounts

1.6 API Parameters

2 Customer Service API - Send Message

3 Customer Service API - Customer Service Typing Status

# Customer Service Account Management

When the developer completes the development as required by the development documentation, after the Official Account replies to the Weixin users via Weixin 6.0.2 or above with different customer service accounts, the users can see the profile photo and alias of the corresponding customer service personnel.

Note that this capability can be used only after the Weixin ID of the Official Account is set on the Official Accounts Platform.

# Adding Customer Service Accounts

Developers can add up to 10 customer service accounts for each Official Account via this API. The API call request is as follows:

HTTP request method: POST
https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN

POST data example:

{
     "kf_account" : "test1@test",
     "nickname" : "Customer Service 1",
     "password" : "pswmd5"
}

Response (The returned JSON packet for a successful request):

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

When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.

# Modifying Customer Service Accounts

Developers can modify customer service accounts for Official Accounts via this API. The API call request is as follows:

HTTP request method: POST
https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN

POST data example:

{
     "kf_account" : "test1@test",
     "nickname" : "Customer Service 1",
     "password" : "pswmd5"
}

Response (The returned JSON packet for a successful request):

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

When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.

# Deleting Customer Service Accounts

Developers can delete customer service accounts for Official Accounts via this API. The API call request is as follows:

HTTP request method: GET
https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN

POST data example:

{
     "kf_account" : "test1@test",
     "nickname" : "Customer Service 1",
     "password" : "pswmd5"
}

Response (The returned JSON packet for a successful request):

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

When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.

# Setting Profile Photo of Customer Service Accounts

This API is used to upload images as the profile photo of the customer service personnel. Only JPG images are supported with the recommended size of 640*640. The API call request is as follows:

HTTP request method: POST/FORM
http://api.weixin.qq.com/customservice/kfaccount/uploadheadimg?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
Calling example: Using the curl command to upload a multimedia file via FORM. Learn about the usage of the curl command by yourself.

Response (The returned JSON packet for a successful request):

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

When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.

# Getting All Customer Service Accounts

Developers can obtain the basic information of customer service set in the Official Account, including customer service ID, customer service alias, and customer service login account.

HTTP request method: GET
https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN

Response (The returned JSON packet for a successful request):

{
    "kf_list": [
        {
            "kf_account": "test1@test", 
            "kf_nick": "ntest1", 
            "kf_id": "1001",
            "kf_headimgurl": " http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0"
        }, 
        {
            "kf_account": "test2@test", 
            "kf_nick": "ntest2", 
            "kf_id": "1002",
            "kf_headimgurl": " http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw /0"
        }, 
        {
            "kf_account": "test3@test", 
            "kf_nick": "ntest3", 
            "kf_id": "1003",
            "kf_headimgurl": " http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw /0"
        }
    ]
}

When an error occurs, Weixin will return an error code and other information. See the error message based on the error code.

# API Parameters

Parameter Required Description
access_token Yes The credential for calling the API
kf_account Yes Complete customer service account, in the format of "Account prefix@Official Account's Weixin ID".
kf_nick Yes Customer service's alias
kf_id Yes Customer service ID
nickname Yes Customer service's alias, with a maximum length of 6 Chinese characters (12 English characters).
password No Login password of customer service account, displayed as a 32-bit MD5 value of the plaintext password. This password is only used in the multi-customer service feature on the Official Accounts Platform. If the multi-customer service feature is not used, the password is not required.
media Yes This parameter is only required to set customer service's profile photo. It is the identifier of the media file in form-data, including information such as filename, filelength, and content-type.

# Customer Service API - Send Message

API request format

HTTP request method: POST
https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

The JSON data packets required for various message types are as follows:

Send a text message

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    }
}

When sending a text message, you can add a text link that can redirect to a Mini Program.

Text content<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">Tap to redirect to the Mini Program</a>

Notes:

  1. In data-miniprogram-appid, enter the AppID of the Mini Program. By tapping the link, the user is redirected to the Mini Program.
  2. In data-miniprogram-path, enter the path to the Mini Program. The path must be the same as that in app.json and can contain parameters.
  3. For Weixin versions that do not support data-miniprogram-appid, if a herf is available, the webpage link in the herf is still used to redirect to the Mini Program.
  4. The Mini Program corresponding to data-miniprogram-appid must be linked with the Official Account.

Send an image message

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

Send a voice message

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

Send a video message

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

Send a music message

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

Send an article (redirected to an external link once tapped) Only one article can be sent. If more than one article is sent, error code 45008 is returned.

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

Send an article (redirected to the article page once tapped) Only one article can be sent. If more than one article is sent, error code 45008 is returned.

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

Send a menu message

{
  "touser": "OPENID"
  "msgtype": "msgmenu",
  "msgmenu": {
    "head_content": "Are you satisfied with the service? "
    "list": [
      {
        "id": "101",
        "content": "Satisfied"
      },
      {
        "id": "102",
        "content": "Dissatisfied"
      }
    ],
    "tail_content": "Looking forward to your visit again"
  }
}

The user will see a menu message like this:

"Are you satisfied with the service?

Satisfied

Dissatisfied"

"Satisfied" and "Dissatisfied" are selectable. After a user selects one, Weixin will send an XML message to the developer's server in the following format:

<xml>
<ToUserName><![CDATA[ToUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>1500000000</CreateTime>
<MsgType><![CDATA[text]]></MsgType>
<Content><![CDATA[Satisfied]]></Content>
<MsgId>1234567890123456</MsgId>
<bizmsgmenuid>101</bizmsgmenuid>
</xml>

XML parameters:

Parameter Description
ToUserName Developer's account
FromUserName Recipient's account (OpenID)
CreateTime Timestamp of the creation time of the message
MsgType Text
Content Name of the menu tapped
MsgId Message ID
bizmsgmenuid ID of the menu tapped

After receiving the XML push, the developer can identify the menu tapped by the Weixin user based on the extracted bizmsgmenuid and Content.


Send a coupon

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

Note that only coupons with non-custom codes and imported codes can be issued via the Customer Service Messages API. For details, see Create Coupons.

Send a Mini Program card (the Mini Program must be linked with the Official Account)

The card is displayed on the app as below:

API calling example:

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

Note that if you need to send a message using a customer service account (the custom profile photo is displayed in Weixin 6.0.2 or above), you should add the customservice parameter in the second half of the JSON packet. For example, to send a text message, modify the packet as follows:

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    },
    "customservice":
    {
         "kf_account": "test1@kftest"
    }
}
Parameter Required Description
access_token Yes The credential for calling the API
touser Yes The openid of an ordinary user
msgtype Yes Message type, including texts (parameter = "text"), images (parameter = "image"), voices (parameter = "voice"), videos (parameter = "video"), music (parameter = "music"), articles (parameter = "news" if redirected to an external link once tapped), articles (parameter = "mpnews" if redirected to the article page once tapped), coupons (parameter = "wxcard"), and Mini Programs (parameter = "miniprogrampage").
content Yes Text message content
media_id Yes The media ID of the image/voice/video/article (redirected to the article page once tapped) to be sent
thumb_media_id Yes The mdeia ID of the thumbnail/Mini Program card image. The recommended size of Mini Program card images is 520*416.
title No The title of the article/video message/music message/Mini Program card
description No The description of the article/video message/music message
musicurl Yes The music's URL
hqmusicurl Yes The high-quality music's URL, which is used preferentially in a Wi-Fi environment.
url No The URL to which an article is redirected once tapped
picurl No The URL of the image in an article. The JPG and PNG formats are supported. Preferred resolutions are 640*320 pixels for large images and 80*80 pixels for thumbnails.
appid Yes The Mini Program's appid. The appid must be linked to the Official Account.
pagepath Yes The page path of a Mini Program. It is aligned with app.json, and supports parameters, for example, pages/index/index?foo=bar.

# Customer Service Typing Status

Developers can return the current typing status of the customer service to users by calling the "Customer Service Typing Status" API.

The status is displayed in the Weixin app as below:

This API requires the permission of the Customer Service Messages API.

  1. If trigger conditions of sending customer service messages are not met, typing status cannot be sent.

  2. To send typing status, there should be message interactions between the user and the customer service within the last 30 seconds.

  3. When the customer service is typing (lasting for 15s), the developer cannot send typing status repeatedly.

  4. When the customer service is typing, if messages are forwarded to the user, the typing status is canceled at the same time.

API request format

HTTP request method: GET

The JSON packet is as below:

 { "touser":"OPENID", "command":"Typing"}

Expected response:

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

Parameters:

Parameter Required Description
access_token Yes The credential for calling the API
touser Yes Ordinary user (openid)
command Yes "Typing": Deliver the "Typing" status to the user; "CancelTyping: Cancel the "Typing" status displayed to the user

Error codes

Parameter Description
45072 Incorrect value in the command field
45080 To send typing status, there should be message interactions with the user within the last 30 seconds.
45081 Already in the "Typing" status. The "Typing" status cannot be delivered repeatedly.