Skip to content

Commit 8f20f3b

Browse files
CopilotCopilot
authored
🆕 #3678 【小程序】新增客服管理相关接口
1 parent 93a2fa7 commit 8f20f3b

File tree

13 files changed

+767
-0
lines changed

13 files changed

+767
-0
lines changed

‎MINIAPP_KEFU_SERVICE.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# WeChat Mini Program Customer Service Management
2+
3+
This document describes the new customer service management functionality added to the WxJava Mini Program SDK.
4+
5+
## Overview
6+
7+
Previously, the mini program module only had:
8+
- `WxMaCustomserviceWorkService` - For binding mini programs to enterprise WeChat customer service
9+
- `WxMaMsgService.sendKefuMsg()` - For sending customer service messages
10+
11+
The new `WxMaKefuService` adds comprehensive customer service management capabilities:
12+
13+
## Features
14+
15+
### Customer Service Account Management
16+
- `kfList()` - Get list of customer service accounts
17+
- `kfAccountAdd()` - Add new customer service account
18+
- `kfAccountUpdate()` - Update customer service account
19+
- `kfAccountDel()` - Delete customer service account
20+
21+
### Session Management
22+
- `kfSessionCreate()` - Create customer service session
23+
- `kfSessionClose()` - Close customer service session
24+
- `kfSessionGet()` - Get customer session status
25+
- `kfSessionList()` - Get customer service session list
26+
27+
## Usage Example
28+
29+
```java
30+
// Get the customer service management service
31+
WxMaKefuService kefuService = wxMaService.getKefuService();
32+
33+
// Add a new customer service account
34+
WxMaKfAccountRequest request = WxMaKfAccountRequest.builder()
35+
.kfAccount("service001@example")
36+
.kfNick("Customer Service 001")
37+
.kfPwd("password123")
38+
.build();
39+
boolean result = kefuService.kfAccountAdd(request);
40+
41+
// Create a session between user and customer service
42+
boolean sessionResult = kefuService.kfSessionCreate("user_openid", "service001@example");
43+
44+
// Get customer service list
45+
WxMaKfList kfList = kefuService.kfList();
46+
```
47+
48+
## Bean Classes
49+
50+
### Request Objects
51+
- `WxMaKfAccountRequest` - For customer service account operations
52+
- `WxMaKfSessionRequest` - For session operations
53+
54+
### Response Objects
55+
- `WxMaKfInfo` - Customer service account information
56+
- `WxMaKfList` - List of customer service accounts
57+
- `WxMaKfSession` - Session information
58+
- `WxMaKfSessionList` - List of sessions
59+
60+
## API Endpoints
61+
62+
The service uses the following WeChat Mini Program API endpoints:
63+
- `https://api.weixin.qq.com/cgi-bin/customservice/getkflist` - Get customer service list
64+
- `https://api.weixin.qq.com/customservice/kfaccount/add` - Add customer service account
65+
- `https://api.weixin.qq.com/customservice/kfaccount/update` - Update customer service account
66+
- `https://api.weixin.qq.com/customservice/kfaccount/del` - Delete customer service account
67+
- `https://api.weixin.qq.com/customservice/kfsession/create` - Create session
68+
- `https://api.weixin.qq.com/customservice/kfsession/close` - Close session
69+
- `https://api.weixin.qq.com/customservice/kfsession/getsession` - Get session
70+
- `https://api.weixin.qq.com/customservice/kfsession/getsessionlist` - Get session list
71+
72+
## Integration
73+
74+
The service is automatically available through the main `WxMaService` interface:
75+
76+
```java
77+
WxMaKefuService kefuService = wxMaService.getKefuService();
78+
```
79+
80+
This fills the gap mentioned in the original issue and provides full customer service management capabilities for WeChat Mini Programs.

‎weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaKefuService.java‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
package cn.binarywang.wx.miniapp.api;
2+
3+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfInfo;
4+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfList;
5+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfSession;
6+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfSessionList;
7+
import cn.binarywang.wx.miniapp.bean.kefu.request.WxMaKfAccountRequest;
8+
import me.chanjar.weixin.common.error.WxErrorException;
9+
10+
/**
11+
* <pre>
12+
* 小程序客服管理接口.
13+
* 不同于 WxMaCustomserviceWorkService (企业微信客服绑定) 和 WxMaMsgService.sendKefuMsg (发送客服消息),
14+
* 此接口专门处理小程序客服账号管理、会话管理等功能。
15+
*
16+
* 注意：小程序客服管理接口与公众号客服管理接口在API端点和功能上有所不同。
17+
* </pre>
18+
*
19+
* @author <a href="https://github.com/binarywang">Binary Wang</a>
20+
*/
21+
public interface WxMaKefuService {
22+
23+
/**
24+
* <pre>
25+
* 获取客服基本信息
26+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.getContactList.html">获取客服基本信息</a>
27+
* 接口url格式：https://api.weixin.qq.com/cgi-bin/customservice/getkflist?access_token=ACCESS_TOKEN
28+
* </pre>
29+
*
30+
* @return 客服列表
31+
* @throws WxErrorException 异常
32+
*/
33+
WxMaKfList kfList() throws WxErrorException;
34+
35+
/**
36+
* <pre>
37+
* 添加客服账号
38+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.addKfAccount.html">添加客服账号</a>
39+
* 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/add?access_token=ACCESS_TOKEN
40+
* </pre>
41+
*
42+
* @param request 客服账号信息
43+
* @return 是否成功
44+
* @throws WxErrorException 异常
45+
*/
46+
boolean kfAccountAdd(WxMaKfAccountRequest request) throws WxErrorException;
47+
48+
/**
49+
* <pre>
50+
* 修改客服账号
51+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.updateKfAccount.html">修改客服账号</a>
52+
* 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/update?access_token=ACCESS_TOKEN
53+
* </pre>
54+
*
55+
* @param request 客服账号信息
56+
* @return 是否成功
57+
* @throws WxErrorException 异常
58+
*/
59+
boolean kfAccountUpdate(WxMaKfAccountRequest request) throws WxErrorException;
60+
61+
/**
62+
* <pre>
63+
* 删除客服账号
64+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.deleteKfAccount.html">删除客服账号</a>
65+
* 接口url格式：https://api.weixin.qq.com/customservice/kfaccount/del?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
66+
* </pre>
67+
*
68+
* @param kfAccount 客服账号
69+
* @return 是否成功
70+
* @throws WxErrorException 异常
71+
*/
72+
boolean kfAccountDel(String kfAccount) throws WxErrorException;
73+
74+
/**
75+
* <pre>
76+
* 创建会话
77+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.createSession.html">创建会话</a>
78+
* 接口url格式：https://api.weixin.qq.com/customservice/kfsession/create?access_token=ACCESS_TOKEN
79+
* </pre>
80+
*
81+
* @param openid 用户openid
82+
* @param kfAccount 客服账号
83+
* @return 是否成功
84+
* @throws WxErrorException 异常
85+
*/
86+
boolean kfSessionCreate(String openid, String kfAccount) throws WxErrorException;
87+
88+
/**
89+
* <pre>
90+
* 关闭会话
91+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.closeSession.html">关闭会话</a>
92+
* 接口url格式：https://api.weixin.qq.com/customservice/kfsession/close?access_token=ACCESS_TOKEN
93+
* </pre>
94+
*
95+
* @param openid 用户openid
96+
* @param kfAccount 客服账号
97+
* @return 是否成功
98+
* @throws WxErrorException 异常
99+
*/
100+
boolean kfSessionClose(String openid, String kfAccount) throws WxErrorException;
101+
102+
/**
103+
* <pre>
104+
* 获取客户的会话状态
105+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.getSession.html">获取客户的会话状态</a>
106+
* 接口url格式：https://api.weixin.qq.com/customservice/kfsession/getsession?access_token=ACCESS_TOKEN&openid=OPENID
107+
* </pre>
108+
*
109+
* @param openid 用户openid
110+
* @return 会话信息
111+
* @throws WxErrorException 异常
112+
*/
113+
WxMaKfSession kfSessionGet(String openid) throws WxErrorException;
114+
115+
/**
116+
* <pre>
117+
* 获取客服的会话列表
118+
* 详情请见：<a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-service/customerServiceMessage.getSessionList.html">获取客服的会话列表</a>
119+
* 接口url格式：https://api.weixin.qq.com/customservice/kfsession/getsessionlist?access_token=ACCESS_TOKEN&kf_account=KFACCOUNT
120+
* </pre>
121+
*
122+
* @param kfAccount 客服账号
123+
* @return 会话列表
124+
* @throws WxErrorException 异常
125+
*/
126+
WxMaKfSessionList kfSessionList(String kfAccount) throws WxErrorException;
127+
128+
}

‎weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/WxMaService.java‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,13 @@ WxMaApiResponse execute(
285285
*/
286286
WxMaCustomserviceWorkService getCustomserviceWorkService();
287287

288+
/**
289+
* 获取小程序客服管理服务。
290+
*
291+
* @return 客服管理服务对象WxMaKefuService
292+
*/
293+
WxMaKefuService getKefuService();
294+
288295
/**
289296
* 获取jsapi操作相关服务对象。
290297
*

‎weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/BaseWxMaServiceImpl.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ public abstract class BaseWxMaServiceImpl<H, P> implements WxMaService, RequestH
113113
private final WxMaAnalysisService analysisService = new WxMaAnalysisServiceImpl(this);
114114
private final WxMaCodeService codeService = new WxMaCodeServiceImpl(this);
115115
private final WxMaCustomserviceWorkService customserviceWorkService = new WxMaCustomserviceWorkServiceImpl(this);
116+
private final WxMaKefuService maKefuService = new WxMaKefuServiceImpl(this);
116117
private final WxMaInternetService internetService = new WxMaInternetServiceImpl(this);
117118
private final WxMaSettingService settingService = new WxMaSettingServiceImpl(this);
118119
private final WxMaJsapiService jsapiService = new WxMaJsapiServiceImpl(this);
@@ -658,6 +659,11 @@ public WxMaCustomserviceWorkService getCustomserviceWorkService() {
658659
return this.customserviceWorkService;
659660
}
660661

662+
@Override
663+
public WxMaKefuService getKefuService() {
664+
return this.maKefuService;
665+
}
666+
661667
@Override
662668
public WxMaJsapiService getJsapiService() {
663669
return this.jsapiService;

‎weixin-java-miniapp/src/main/java/cn/binarywang/wx/miniapp/api/impl/WxMaKefuServiceImpl.java‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
package cn.binarywang.wx.miniapp.api.impl;
2+
3+
import cn.binarywang.wx.miniapp.api.WxMaKefuService;
4+
import cn.binarywang.wx.miniapp.api.WxMaService;
5+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfInfo;
6+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfList;
7+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfSession;
8+
import cn.binarywang.wx.miniapp.bean.kefu.WxMaKfSessionList;
9+
import cn.binarywang.wx.miniapp.bean.kefu.request.WxMaKfAccountRequest;
10+
import cn.binarywang.wx.miniapp.bean.kefu.request.WxMaKfSessionRequest;
11+
import lombok.RequiredArgsConstructor;
12+
import me.chanjar.weixin.common.error.WxErrorException;
13+
14+
/**
15+
* 小程序客服管理服务实现.
16+
*
17+
* @author <a href="https://github.com/binarywang">Binary Wang</a>
18+
*/
19+
@RequiredArgsConstructor
20+
public class WxMaKefuServiceImpl implements WxMaKefuService {
21+
22+
// 小程序客服管理接口URL
23+
private static final String KFLIST_GET_URL = "https://api.weixin.qq.com/cgi-bin/customservice/getkflist";
24+
private static final String KFACCOUNT_ADD_URL = "https://api.weixin.qq.com/customservice/kfaccount/add";
25+
private static final String KFACCOUNT_UPDATE_URL = "https://api.weixin.qq.com/customservice/kfaccount/update";
26+
private static final String KFACCOUNT_DEL_URL = "https://api.weixin.qq.com/customservice/kfaccount/del?kf_account=%s";
27+
private static final String KFSESSION_CREATE_URL = "https://api.weixin.qq.com/customservice/kfsession/create";
28+
private static final String KFSESSION_CLOSE_URL = "https://api.weixin.qq.com/customservice/kfsession/close";
29+
private static final String KFSESSION_GET_URL = "https://api.weixin.qq.com/customservice/kfsession/getsession?openid=%s";
30+
private static final String KFSESSION_LIST_URL = "https://api.weixin.qq.com/customservice/kfsession/getsessionlist?kf_account=%s";
31+
32+
private final WxMaService service;
33+
34+
@Override
35+
public WxMaKfList kfList() throws WxErrorException {
36+
String responseContent = this.service.get(KFLIST_GET_URL, null);
37+
return WxMaKfList.fromJson(responseContent);
38+
}
39+
40+
@Override
41+
public boolean kfAccountAdd(WxMaKfAccountRequest request) throws WxErrorException {
42+
String responseContent = this.service.post(KFACCOUNT_ADD_URL, request.toJson());
43+
return responseContent != null;
44+
}
45+
46+
@Override
47+
public boolean kfAccountUpdate(WxMaKfAccountRequest request) throws WxErrorException {
48+
String responseContent = this.service.post(KFACCOUNT_UPDATE_URL, request.toJson());
49+
return responseContent != null;
50+
}
51+
52+
@Override
53+
public boolean kfAccountDel(String kfAccount) throws WxErrorException {
54+
String url = String.format(KFACCOUNT_DEL_URL, kfAccount);
55+
String responseContent = this.service.get(url, null);
56+
return responseContent != null;
57+
}
58+
59+
@Override
60+
public boolean kfSessionCreate(String openid, String kfAccount) throws WxErrorException {
61+
WxMaKfSessionRequest request = WxMaKfSessionRequest.builder()
62+
.kfAccount(kfAccount)
63+
.openid(openid)
64+
.build();
65+
String responseContent = this.service.post(KFSESSION_CREATE_URL, request.toJson());
66+
return responseContent != null;
67+
}
68+
69+
@Override
70+
public boolean kfSessionClose(String openid, String kfAccount) throws WxErrorException {
71+
WxMaKfSessionRequest request = WxMaKfSessionRequest.builder()
72+
.kfAccount(kfAccount)
73+
.openid(openid)
74+
.build();
75+
String responseContent = this.service.post(KFSESSION_CLOSE_URL, request.toJson());
76+
return responseContent != null;
77+
}
78+
79+
@Override
80+
public WxMaKfSession kfSessionGet(String openid) throws WxErrorException {
81+
String url = String.format(KFSESSION_GET_URL, openid);
82+
String responseContent = this.service.get(url, null);
83+
return WxMaKfSession.fromJson(responseContent);
84+
}
85+
86+
@Override
87+
public WxMaKfSessionList kfSessionList(String kfAccount) throws WxErrorException {
88+
String url = String.format(KFSESSION_LIST_URL, kfAccount);
89+
String responseContent = this.service.get(url, null);
90+
return WxMaKfSessionList.fromJson(responseContent);
91+
}
92+
}

0 commit comments

Comments
 (0)