🆕 #2309 【企业微信】新增微信客服帐号管理部分接口

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpKfService.java

@@ -0,0 +1,70 @@
+package me.chanjar.weixin.cp.api;
+
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountAdd;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountAddResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountDel;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountLink;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountLinkResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountListResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountUpd;
+
+/**
+ * 微信客服接口
+ *
+ *  微信客服由腾讯微信团队为企业打造，用于满足企业的客服需求，帮助企业做好客户服务。企业可以在微信内、外各个场景中接入微信客服，
+ *  用户可以发起咨询，企业可以进行回复。
+ *  企业可在微信客服官网使用企业微信扫码开通微信客服，开通后即可使用。
+ *
+ * @author Fu
+ * @date 2022/1/19 19:25
+ */
+public interface WxCpKfService {
+
+  /**
+   * 添加客服帐号，并可设置客服名称和头像。目前一家企业最多可添加10个客服帐号
+   *
+   * @param add 客服帐号信息
+   * @return result-新创建的客服帐号ID
+   * @throws WxErrorException 异常
+   */
+  WxCpKfAccountAddResp addAccount(WxCpKfAccountAdd add) throws WxErrorException;
+
+  /**
+   * 修改已有的客服帐号，可修改客服名称和头像。
+   *
+   * @param upd 新的客服账号信息
+   * @return result
+   * @throws WxErrorException 异常
+   */
+  WxCpBaseResp updAccount(WxCpKfAccountUpd upd) throws WxErrorException;
+
+  /**
+   * 删除已有的客服帐号
+   *
+   * @param del 要删除的客服帐号
+   * @return result
+   * @throws WxErrorException 异常
+   */
+  WxCpBaseResp delAccount(WxCpKfAccountDel del) throws WxErrorException;
+
+  /**
+   * 获取客服帐号列表，包括所有的客服帐号的客服ID、名称和头像。
+   *
+   * @return 客服帐号列表
+   * @throws WxErrorException 异常
+   */
+  WxCpKfAccountListResp listAccount() throws WxErrorException;
+
+  /**
+   * 企业可通过此接口获取带有不同参数的客服链接，不同客服帐号对应不同的客服链接。获取后，企业可将链接嵌入到网页等场景中，
+   * 微信用户点击链接即可向对应的客服帐号发起咨询。企业可依据参数来识别用户的咨询来源等
+   *
+   * @param link 参数
+   * @return 链接
+   * @throws WxErrorException 异常
+   */
+  WxCpKfAccountLinkResp getAccountLink(WxCpKfAccountLink link) throws WxErrorException;
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/WxCpService.java

@@ -427,6 +427,13 @@ public interface WxCpService extends WxService {
    */
   WxCpAgentWorkBenchService getWorkBenchService();
 
+  /**
+   * 获取微信客服服务
+   *
+   * @return 微信客服服务
+   */
+  WxCpKfService getKfService();
+
   /**
    * http请求对象
    *
@@ -476,4 +483,10 @@ public interface WxCpService extends WxService {
    */
   void setTagService(WxCpTagService tagService);
 
+  /**
+   * Sets kf service.
+   *
+   * @param kfService the kf service
+   */
+  void setKfService(WxCpKfService kfService);
 }

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/BaseWxCpServiceImpl.java

@@ -57,6 +57,7 @@ public abstract class BaseWxCpServiceImpl<H, P> implements WxCpService, RequestH
   private WxCpOaCalendarService oaCalendarService = new WxCpOaCalendarServiceImpl(this);
   private WxCpOaScheduleService oaScheduleService = new WxCpOaOaScheduleServiceImpl(this);
   private WxCpAgentWorkBenchService workBenchService = new WxCpAgentWorkBenchServiceImpl(this);
+  private WxCpKfService kfService = new WxCpKfServiceImpl(this);
 
   /**
    * 全局的是否正在刷新access token的锁.
@@ -556,4 +557,14 @@ public void setAgentService(WxCpAgentService agentService) {
   public WxCpOaScheduleService getOaScheduleService() {
     return this.oaScheduleService;
   }
+
+  @Override
+  public WxCpKfService getKfService() {
+    return kfService;
+  }
+
+  @Override
+  public void setKfService(WxCpKfService kfService) {
+    this.kfService = kfService;
+  }
 }

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/api/impl/WxCpKfServiceImpl.java

@@ -0,0 +1,64 @@
+package me.chanjar.weixin.cp.api.impl;
+
+import lombok.RequiredArgsConstructor;
+import me.chanjar.weixin.common.error.WxErrorException;
+import me.chanjar.weixin.cp.api.WxCpKfService;
+import me.chanjar.weixin.cp.api.WxCpService;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountAdd;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountAddResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountDel;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountLink;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountLinkResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountListResp;
+import me.chanjar.weixin.cp.bean.kf.WxCpKfAccountUpd;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+import static me.chanjar.weixin.cp.constant.WxCpApiPathConsts.Kf.*;
+
+/**
+ * 微信客服接口-服务实现
+ *
+ * @author Fu
+ * @date 2022/1/19 19:41
+ */
+@RequiredArgsConstructor
+public class WxCpKfServiceImpl implements WxCpKfService {
+  private final WxCpService cpService;
+
+  @Override
+  public WxCpKfAccountAddResp addAccount(WxCpKfAccountAdd add) throws WxErrorException {
+    String url = cpService.getWxCpConfigStorage().getApiUrl(ACCOUNT_ADD);
+    String responseContent = cpService.post(url, WxCpGsonBuilder.create().toJson(add));
+    return WxCpKfAccountAddResp.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpBaseResp updAccount(WxCpKfAccountUpd upd) throws WxErrorException {
+    String url = cpService.getWxCpConfigStorage().getApiUrl(ACCOUNT_UPD);
+    String responseContent = cpService.post(url, WxCpGsonBuilder.create().toJson(upd));
+    return WxCpBaseResp.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpBaseResp delAccount(WxCpKfAccountDel del) throws WxErrorException {
+    String url = cpService.getWxCpConfigStorage().getApiUrl(ACCOUNT_DEL);
+    String responseContent = cpService.post(url, WxCpGsonBuilder.create().toJson(del));
+    return WxCpBaseResp.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpKfAccountListResp listAccount() throws WxErrorException {
+    String url = cpService.getWxCpConfigStorage().getApiUrl(ACCOUNT_LIST);
+    String responseContent = cpService.post(url, "{}");
+    return WxCpKfAccountListResp.fromJson(responseContent);
+  }
+
+  @Override
+  public WxCpKfAccountLinkResp getAccountLink(WxCpKfAccountLink link) throws WxErrorException {
+    String url = cpService.getWxCpConfigStorage().getApiUrl(ADD_CONTACT_WAY);
+    String responseContent = cpService.post(url, WxCpGsonBuilder.create().toJson(link));
+    return WxCpKfAccountLinkResp.fromJson(responseContent);
+  }
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/kf/WxCpKfAccountAdd.java

@@ -0,0 +1,33 @@
+package me.chanjar.weixin.cp.bean.kf;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+/**
+ * 添加客服帐号-请求参数
+ *
+ * @author Fu
+ * @date 2022/1/19 18:59
+ */
+@NoArgsConstructor
+@Data
+public class WxCpKfAccountAdd implements Serializable {
+
+  private static final long serialVersionUID = 3565729481246537411L;
+
+  /**
+   * 客服名称；不多于16个字符
+   */
+  @SerializedName("name")
+  private String name;
+
+  /**
+   * 客服头像临时素材。可以调用上传临时素材接口获取。
+   * 不多于128个字节
+   */
+  @SerializedName("media_id")
+  private String mediaId;
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/kf/WxCpKfAccountAddResp.java

@@ -0,0 +1,32 @@
+package me.chanjar.weixin.cp.bean.kf;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+/**
+ * 添加客服帐号-返回结果
+ *
+ * @author Fu
+ * @date 2022/1/19 19:04
+ */
+@EqualsAndHashCode(callSuper = true)
+@NoArgsConstructor
+@Data
+public class WxCpKfAccountAddResp extends WxCpBaseResp {
+
+  private static final long serialVersionUID = -6649323005421772827L;
+
+  /**
+   * 新创建的客服帐号ID
+   */
+  @SerializedName("open_kfid")
+  private String openKfid;
+
+  public static WxCpKfAccountAddResp fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpKfAccountAddResp.class);
+  }
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/kf/WxCpKfAccountDel.java

@@ -0,0 +1,28 @@
+package me.chanjar.weixin.cp.bean.kf;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+/**
+ * 删除客服帐号-请求参数
+ *
+ * @author Fu
+ * @date 2022/1/19 19:09
+ */
+@NoArgsConstructor
+@Data
+public class WxCpKfAccountDel implements Serializable {
+
+  private static final long serialVersionUID = 1997221467585676772L;
+
+  /**
+   * 客服帐号ID。
+   * 不多于64字节
+   */
+  @SerializedName("open_kfid")
+  private String openKfid;
+
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/kf/WxCpKfAccountLink.java

@@ -0,0 +1,40 @@
+package me.chanjar.weixin.cp.bean.kf;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+
+/**
+ * 获取客服帐号链接-请求参数
+ *
+ * @author Fu
+ * @date 2022/1/19 19:18
+ */
+@NoArgsConstructor
+@Data
+public class WxCpKfAccountLink implements Serializable {
+
+  private static final long serialVersionUID = -1920926948347984256L;
+
+  /**
+   * 客服帐号ID
+   */
+  @SerializedName("open_kfid")
+  private String openKfid;
+
+  /**
+   * 场景值，字符串类型，由开发者自定义。
+   * 不多于32字节
+   * 字符串取值范围(正则表达式)：[0-9a-zA-Z_-]*
+   *
+   * 1. 若scene非空，返回的客服链接开发者可拼接scene_param=SCENE_PARAM参数使用，用户进入会话事件会将SCENE_PARAM原样返回。
+   *    其中SCENE_PARAM需要urlencode，且长度不能超过128字节。
+   *    如 https://work.weixin.qq.com/kf/kfcbf8f8d07ac7215f?enc_scene=ENCGFSDF567DF&scene_param=a%3D1%26b%3D2
+   * 2. 历史调用接口返回的客服链接（包含encScene=XXX参数），不支持scene_param参数。
+   * 3. 返回的客服链接，不能修改或复制参数到其他链接使用。否则进入会话事件参数校验不通过，导致无法回调。
+   */
+  @SerializedName("scene")
+  private String scene;
+}

weixin-java-cp/src/main/java/me/chanjar/weixin/cp/bean/kf/WxCpKfAccountLinkResp.java

@@ -0,0 +1,32 @@
+package me.chanjar.weixin.cp.bean.kf;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.NoArgsConstructor;
+import me.chanjar.weixin.cp.bean.WxCpBaseResp;
+import me.chanjar.weixin.cp.util.json.WxCpGsonBuilder;
+
+/**
+ * 获取客服帐号链接-结果
+ *
+ * @author Fu
+ * @date 2022/1/19 19:18
+ */
+@EqualsAndHashCode(callSuper = true)
+@NoArgsConstructor
+@Data
+public class WxCpKfAccountLinkResp extends WxCpBaseResp {
+
+  private static final long serialVersionUID = 910205439597092481L;
+
+  /**
+   * 客服链接，开发者可将该链接嵌入到H5页面中，用户点击链接即可向对应的微信客服帐号发起咨询。开发者也可根据该url自行生成需要的二维码图片
+   */
+  @SerializedName("url")
+  private String url;
+
+  public static WxCpKfAccountLinkResp fromJson(String json) {
+    return WxCpGsonBuilder.create().fromJson(json, WxCpKfAccountLinkResp.class);
+  }
+}