IM客服端 SDK

使用此 sdk，你可以通过简单的配置实现一个 im 客服端工作台。

sdk 地址

https://{公司客服系统域名}/lib/udesk-im/agent-client.js

如何使用

先引入此 js

<script src='https://{公司客服系统域名}/lib/udesk-im/agent-client.js'></script>

创建实例

<script>
//获取 token
function fetchToken(){
    if(fetchToken.cache){ //如果有缓存token，直接返回
        return Promise.resolve(fetchToken.cache);
    }
    return fetch('/token').then((t)=>{
        setTimeout(()=>fetchToken.cache = null,60*60*1000); //1小时重新获取 token，避免 token 失效
        fetchToken.cache=t;   //缓存 token
        return t;
    });
}
const udeskAgentClient = new UdeskAgentClient({
    host: 'xxxx.udesk.cn' //udesk客服系统域名
    getToken: ()=> fetchToken(), //请求后端获取 token
    lang?:'zh-cn'//sdk 语言，支持 中文，英文，日文

})
</script>

创建容器，并渲染到容器中

<!-- 需要给容器一个宽度和高度，否则渲染结果样式会乱 -->
<style>
#udesk-agent-client {
    width: 100%;
    height: 100%;
}
</style>
<div id='udesk-agent-client'></div>
<script>
udeskAgentClient.renderTo(document.getElementById('udesk-agent-client'));
</script>

参数说明

参数	是否必填	说明
getToken	是	()=>Promise,用于鉴权
host	是	udesk客服系统的 host
onNewChat	否	当有新会话的时候触发
lang	否	sdk语言，不传默认为中文，有效值为 'zh-cn'｜'en-us'｜'ja'
onSelectChat	否	选中会话时触发，(chat:{im_sub_session_id:number,session_key:string,customer:{id:number,nick_name:string}})=>void
onCloseChat	否	关闭会话时触发，(chat:{im_sub_session_id:number,session_key:string})=>void

token 生成方式

token 是 JWT 格式。
JWT的秘钥获取: 获取位置在Udesk系统中 管理中心 - 单点登录 - 共享的秘钥
JWT的数据必须包含

{
  "email": "agent@udesk.cn", // 客服邮箱
  "iat": 1605768993, // 格林时间整数, token 生成的时间
}

注意:

JWT_TOKEN的过期时间为 10 小时，需要开发者提供刷新 JWT_TOKEN 的功能

Java 生成 JWT 的例子

1. 安装依赖

<dependency>
    <groupId>org.bitbucket.b_c</groupId>
    <artifactId>jose4j</artifactId>
    <version>0.9.6</version>
</dependency>

2. 代码实现

import org.jose4j.jws.AlgorithmIdentifiers;
import org.jose4j.jws.JsonWebSignature;
import org.jose4j.jwt.JwtClaims;
import org.jose4j.keys.HmacKey;
import org.jose4j.lang.JoseException;

import java.io.UnsupportedEncodingException;
import java.security.Key;

public class UdeskAgentClient {
    public static void main(String[] args) throws JoseException, UnsupportedEncodingException {
        //
        // JSON Web Token（JWT）是一种紧凑的、URL安全的声明/属性传输方式，用于在两端之间传递数据。
        // 这是一个生成JWT的例子。
        //

        // 构建JWT的载荷，这些载荷将成为JWT中的信息或数据。
        JwtClaims claims = new JwtClaims();
        claims.setIssuedAtToNow();  // JWT创建时间（即当前时间）。
        claims.setClaim("email", "agent@example.com"); // 替换为客服的邮箱

        // 请复制 udesk 客服系统管理中心->单点登录页面的“共享的秘钥”
        String secret = "替换为你的密钥";
        Key key = new HmacKey(secret.getBytes("UTF-8"));

        // JWT是携带了JSON格式数据的JWS（JSON Web Signature）或JWE（JSON Web Encryption）。
        // 在这个例子中，我们使用JWS（JSON Web Signature），因此需要创建一个用于签名操作的JsonWebSignature实例。
        JsonWebSignature jws = new JsonWebSignature();

        // 设置载荷，载荷需转成 JSON 格式
        jws.setPayload(claims.toJson());

        // 设置用于签名的 key
        jws.setKey(key);

        // 设置签名算法，用于校验载荷是否正确。
        jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.HMAC_SHA256);

        // 对JWS进行签名处理，并生成其紧凑的序列化形式，
        // 这是一个由三个部分组成的字符串：头部（Header）、载荷（Payload）和签名（Signature），
        // 每个部分都是 base64 编码的。
        String jwt = jws.getCompactSerialization();

        System.out.println("JWT: " + jwt);
    }
}