Contents

1.1 Getting Basic Customer Service Information

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 Weixin 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 Weixin ID, the Weixin ID is displayed.
invite_wx	If the Customer Service account has not been linked with a Weixin ID, but a linking invitation has been initiated, then the Weixin ID to be linked is displayed.
invite_expire_time	If the Customer Service account has not been linked with a Weixin 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 Weixin 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 Weixin ID". The account prefix includes up to 10 characters and only supports letters, numbers or underscores (_). The suffix is the Official Account's Weixin 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 Weixin ID to the Customer Service account. This API initiates a linking invitation to the Customer Service personnel's Weixin ID, and the Customer Service personnel cannot use this account until it confirms the invitation using this Weixin ID on the Weixin app. An invitation can be initiated for any account that has not been linked to a Weixin 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 Weixin ID"
invite_wx	The Customer Service's Weixin 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 Weixin ID
65409	Invalid Weixin ID
65410	The number of Official Account Customer Service accounts that the invitee is invited to link with has reached the limit (each Weixin 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 Weixin 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 Weixin 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 Weixin 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 Weixin 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 Weixin ID
65409	Invalid Weixin ID
65410	The number of Official Account Customer Service accounts that the invitee is invited to link with has reached the limit (each Weixin 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 Weixin ID
40005	Unsupported media type
40009	Media file length is invalid