Contents

1.1 Getting Basic Customer Service Information

1.2 Adding Customer Service Accounts

1.3 Inviting to Link Customer Service Accounts

1.4 Setting Customer Service Information

1.5 Uploading Customer Service's Profile Photo

1.6 Deleting Customer Service Accounts

1.7 Error Code for Customer Service Management APIs

Getting Basic Customer Service Information

Calling Method

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

Response Description

Example of response data (The returned JSON packet for a successful request):

{
      "kf_list" : [
         {
            "kf_account" : "test1@test",
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1001",
            "kf_nick" : "ntest1",
            "kf_wx" : "kfwx1"
         },
         {
            "kf_account" : "test2@test",
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1002",
            "kf_nick" : "ntest2",
            "kf_wx" : "kfwx2"
         },
         {
            "kf_account" : "test3@test",
            "kf_headimgurl" : "http://mmbiz.qpic.cn/mmbiz/4whpV1VZl2iccsvYbHvnphkyGtnvjfUS8Ym0GSaLic0FD3vN0V8PILcibEGb2fPfEOmw/0",
            "kf_id" : "1003",
            "kf_nick" : "ntest3",
            "invite_wx" : "kfwx3",
            "invite_expire_time" : 123456789,
            "invite_status" : "waiting"
         }
      ]
}

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID"
kf_nick Customer Service's alias
kf_id Customer Service ID
kf_headimgurl Customer Service's profile photo
kf_wx If the Customer Service account has been linked with the Customer Service personnel's WeChat ID, the WeChat ID is displayed.
invite_wx If the Customer Service account has not been linked with a WeChat ID, but a linking invitation has been initiated, then the WeChat ID to be linked is displayed.
invite_expire_time If the Customer Service account has not been linked with a WeChat ID, but a linking invitation has been initiated, the expiration time of the invitation is a Unix timestamp.
invite_status Invitation status. waiting: Pending confirmation; rejected: Rejected; expired: Expired

Calling Method

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

Response Description

Return data example (the JSON return result for a successful request):
 {
     "kf_online_list" : [
         {
             "kf_account" :
  "test1@test" ,
              "status" : 1,
              "kf_id" :
  "1001" ,
              "accepted_case" : 1
         },
         {
             "kf_account" :
  "test2@test" ,
              "status" : 1,
              "kf_id" :
  "1002" ,
              "accepted_case" : 2
         }
     ]
 }
 

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID"
status Online status of Customer Service. 1: Web
kf_id Customer service ID
accepted_case The number of chats currently received by the Customer Service

Adding Customer Service Accounts

Calling Method

HTTP request method: POST https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN POST data example is as follows:
   {
      "kf_account" : "test1@test",
      "nickname" : "Customer Service 1"
   }

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID". The account prefix includes up to 10 characters and only supports letters, numbers or underscores (_). The suffix is the Official Account's WeChat ID, with a maximum length of 30 characters.
nickname Customer service alias, with a maximum of 16 Chinese characters (32 English characters)

Response Description

Example of response data (The returned JSON packet for a successful request):
   {
      "errcode"
   : 0,
      "errmsg"
   :
  "ok"
   }

Common Error Code

Error Code Description
0 Successful
65400 API is not available. The latest version of Customer Service feature is not enabled or the Customer Service feature is not upgraded to the latest version.
65403 Invalid customer service alias
65404 Invalid customer service account
65405 The number of accounts has reached the limit, and no more accounts can be added.
65406 The Customer Service account already exists

Inviting to Link Customer Service Accounts

The new Customer Service account cannot be used directly. The Customer Service personnel can log in to the Web Customer Service system only after linking its WeChat ID to the Customer Service account. This API initiates a linking invitation to the Customer Service personnel's WeChat ID, and the Customer Service personnel cannot use this account until it confirms the invitation using this WeChat ID on the WeChat app. An invitation can be initiated for any account that has not been linked to a WeChat ID. When an invitation is not expired, it cannot be sent again.

Calling Method

HTTP request method: POST https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN POST data example is as follows:
   {
      "kf_account" : "test1@test",
      "invite_wx" : "test_kfwx"
   }

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID"
invite_wx The Customer Service's WeChat ID that receives the linking invitation

Response Description

Example of response data (The returned JSON packet for a successful request):
   {
      "errcode"
   : 0,
      "errmsg"
   :
  "ok"
   } 

Common Error Code

Error Code Description
0 Successful
65400 API is not available. The latest version of Customer Service is not enabled or the Customer Service is not upgraded to the latest version.
65401 Invalid Customer Service account
65407 The invitee is already the Customer Service of this Official Account
65408 This Official Account has sent an invitation to the WeChat ID
65409 Invalid WeChat ID
65410 The number of Official Account Customer Service accounts that the invitee is invited to link with has reached the limit (each WeChat ID can be linked with at most 5 Official Account Customer Service accounts)
65411 This account already has an invitation to be confirmed. Re-initiating the invitation is not allowed.
65412 Invitation is not allowed because this account has already linked with a WeChat ID

Setting Customer Service Information

Calling Method

HTTP request method: POST https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN POST data example is as follows:
   {
      "kf_account" : "test1@test",
      "nickname" : "Customer Service 1"
   }

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID"
nickname Customer service alias, with a maximum of 16 Chinese characters (32 English characters)

Response Description

Example of response data (The returned JSON packet for a successful request):
   {
      "errcode"
   : 0,
      "errmsg"
   :
  "ok"
   } 

Common Error Code

Error Code Description
0 Successful
65400 API unavailable, because Customer Service is not enabled or updated to the latest version.
65401 Invalid customer service account
65403 Invalid customer service alias

Uploading Customer Service's Profile Photo

Calling Method

HTTP request method: POST/FORM
 https://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):
 curl -F media=@test.jpg "https://api.weixin.qq.com/customservice/kfaccount/uploadheadimg?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT" 

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID"
media The identifier of the media file in form-data, including information such as filename, filelength, and content-type. File size is limited to 5 MB.

Response Description

Example of response data (The returned JSON packet for a successful request):
   {
      "errcode"
   : 0,
      "errmsg"
   :
  "ok"
   } 

Common Error Code

Error Code Description
0 Successful
65400 API unavailable, because Customer Service is not enabled or updated to the latest version.
65401 Invalid customer service account
65403 Invalid customer service alias
40005 Unsupported media type
40009 Media file length is invalid

Deleting Customer Service Accounts

Calling Method

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

Parameters

Parameter Description
kf_account Complete Customer Service account, in the format of "Account prefix@Official Account's WeChat ID"

Response Description

Example of response data (The returned JSON packet for a successful request):
   {
      "errcode"
   : 0,
      "errmsg"
   :
  "ok"
   } 

Common Error Code

Error Code Description
0 Successful
65400 API unavailable, because Customer Service is not enabled or updated to the latest version.
65401 Invalid customer service account

Error Code for Customer Service Management APIs

Error Code Description
0 Successful
65400 API unavailable, because Customer Service is not enabled or updated to the latest version.
65401 Invalid customer service account
65403 Invalid customer service alias
65404 Invalid customer service account
65405 The number of accounts has reached the limit, and no more accounts can be added.
65406 The customer service account already exists
65407 The invitee is already the Customer Service of the Official Account
65408 This Official Account has sent an invitation to the WeChat ID
65409 Invalid WeChat ID
65410 The number of Official Account Customer Service accounts that the invitee is invited to link with has reached the limit (each WeChat ID can only be linked with 5 Official Account Customer Service accounts)
65411 This account already has an invitation to be confirmed. Re-initiating the invitation is not allowed.
65412 Invitation is not allowed because this account has already linked with a WeChat ID
40005 Unsupported media type
40009 Media file length is invalid