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

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

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"
    }
}

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

Error codes