Udesk WebIM网页插件

您好,欢迎接入Udesk WebIM网页插件(WebIM), 以下提供基本用法、注意事项、参数说明、方法说明、事件说明、相关示例等。

基本用法

登陆Udesk客服系统管理员账号,在 管理中心 -> 即时通讯 -> 网页插件【管理】,配置基本属性后复制代码到网页,即可启用Udesk IM。

注意事项

设备支持

WebIM目前支持PC/Android(含平板)/IOS(含平板)等设备。

浏览器兼容性

WebIM目前支持IE8+(含)的IE浏览器与基于它内核(360/qq/...)、其他主流浏览器(chrome/firefox/...)。

基本示例

内嵌代码示例

<body>
    <!-- 网页内容 具体代码请在管理员即时通讯网页插件处复制 -->

    <script>
    (function(a,h,c,b,f,g){a["UdeskApiObject"]=f;a[f]=a[f]||function(){(a[f].d=a[f].d||[]).push(arguments)};g=h.createElement(c);g.async=1;g.src=b;c=h.getElementsByTagName(c)[0];c.parentNode.insertBefore(g,c)})(window,document,"script","http://xxx.xxxx.cn/im_client/js/udeskApi.js?1487931175918","ud");
    ud({
        "code": "xxxx",
        "link": "http://xxx.xxxx.cn/im_client/?web_plugin_id=1",
        "isInvite": true,
        "mode": "inner",
        "color": "#307AE8",
        "pos_flag": "srb",
        "language": "en-us", //语言-英文
        "onlineText": "联系客服,在线咨询",
        "offlineText": "客服下班,请留言",
        "mobile": { //为响应式布局,提供pc、mobile自定制
            "mode": "blank",
            "color": "#307AE8",
            "pos_flag": "crb",
            "onlineText": "联系客服,在线咨询",
            "offlineText": "客服下班,请留言"
        }
    });
    </script>
</body>

链接示例

http://xxx.xxxx.cn/im_client/?web_plugin_id=xx&language=zh-cn&agent_id=xxx&group_id=xxx

自定义配置

开发者可以根据自己的需求自定义相关配置,所有属性、事件都在ud({...})里面进行配置,所有方法通过ud.functionName()的方式调用。

配置方式

1. ud({key: val, key2: val2, ...});
2. ud(key, val);

自适应协议

将所有的链接地址 http(s):// 替换为 //

(function(a,h,c,b,f,g){a["UdeskApiObject"]=f;a[f]=a[f]||function(){(a[f].d=a[f].d||[]).push(arguments)};g=h.createElement(c);g.async=1;g.src=b;c=h.getElementsByTagName(c)[0];c.parentNode.insertBefore(g,c)})(window,document,"script","//xxx.xxxx.cn/im_client/js/udeskApi.js?1487931175918","ud");
ud({
    "link": "//xxx.xxxx.cn/im_client/"
});

参数说明

全局参数

参数名称 类型 是否必需 说明
code String 系统生成 公司唯一标识
link String 系统生成 公司IM Client链接地址
isInvite Boolean true或false(默认) 是否开启访客邀请功能
管理台可配
agent_id String 指定客服ID,默认不指定 指定会话的客服人员
group_id String 指定客服组ID,默认不指定 指定会话的客服组
session_key String 6位随机字符串 同一个客户,不同的sesstion_key会触发新的会话
mode String inner:网页内嵌模式(默认)
blank:独立窗口模式
按钮打开窗口显示模式
管理台可配
color String 按钮颜色代码,默认为:#307AE8 配置IM按钮颜色
管理台可配
pos_flag String 按钮形状+位置
1)形状: h(横向) v(纵向) c(圆形) i(图片);
2)位置: lt(左上) mt(中上) rt(右上) lm(左中) mm(正中) rm(右中) lb(左下) mb(中下) rb(右下)
默认值:crb(pc),hrb(mobile)
按钮形状+位置
如:vrb(横向右下角)
管理台可配
onlineText String 客服在线显示文本,默认为“联系客服,在线咨询” 管理台可配
offlineText String 客服离线显示文本,默认为“客服下班,请留言” 管理台可配
noBubble Boolean true或false(默认) 不显示消息弹出气泡提醒
manualInit Boolean true或false(默认) 手动初始化,设置为true时,嵌入代码不会自动初始化,需要主动调用ud.init()方法
language String "zh-cn"(表示中文)、"en-us"(表示英文)等 配置客户端多语言[详情]
channel String 自定义渠道 管理台可配
targetSelector String 支持#id,.class,tagName,...
默认系统生成 唯一
主目标按钮选择器
1) 用于触发聊天窗口
2) 用于代替系统默认提供的按钮,指定有效后默认按钮不再显示
3) 用于接收邀请
4) 用于接收新消息提醒
5) ...
selector String 支持#id,.class,tagName,...
默认无 可多个
辅助按钮选择器
1) 用于触发聊天窗口
css Object 按钮自定义样式,如:css:{top:10%},默认无
window Object 仅独立窗口模式 独立窗口默认大小为宽780,高560
例 window: {"width": "780", "height": "560"}
配置打开独立窗口大小
panel Object 仅网页内嵌模式 会话面板 [详情]
pop Object 消息提醒气泡 [详情]
customer Object 客户信息 [详情]
product Object 咨询对象 [详情]
mobile Object 移动端相关配置 [详情]
当网站为响应式布局,提供pc、mobile自定制

示例

ud({
    "code": "xxxx",
    "link": "http://xxx.xxxx.cn/im_client/",
    "mode": "inner",
    "color": "#307AE8",
    "pos_flag": "srb",
    "session_key": "afeoqe",
    "onlineText": "联系客服,在线咨询",
    "offlineText": "客服下班,请留言",
    "targetSelector": "#btn_udesk_im",
    "selector": ".udesk_im",
    "pop": {},
    "panel": {},
    "mobile": {},
    "window": {}
});

> 移动端 - 参数说明

参数名称 类型 是否必选 说明
mode String inner:网页内嵌模式(默认)
blank:独立窗口模式
按钮打开窗口显示模式
管理台可配
color String 按钮颜色代码,默认为:#307AE8 配置IM按钮颜色
管理台可配
pos_flag String 按钮形状+位置
1)形状: h(横向) v(纵向) c(圆形) i(图片);
2)位置: lt(左上) mt(中上) rt(右上) lm(左中) mm(正中) rm(右中) lb(左下) mb(中下) rb(右下)
默认值:crb(pc),hrb(mobile)
按钮形状+位置
如:vrb(横向右下角)
管理台可配
onlineText String 客服在线显示文本,默认为“联系客服,在线咨询” 管理台可配
offlineText String 客服离线显示文本,默认为“客服下班,请留言” 管理台可配
noBubble Boolean true或false(默认) 不显示消息弹出气泡提醒
language String "zh-cn"(中文) 或 "en-us"(英文) 配置客户端多语言
targetSelector String 支持#id,.class,tagName,...
默认系统生成 唯一
主目标按钮选择器
1) 用于触发聊天窗口
2) 用于代替系统默认提供的按钮,指定有效后默认按钮不再显示
3) 用于接收邀请
4) 用于接收新消息提醒
5) ...
selector String 支持#id,.class,tagName,...
默认无 可多个
辅助按钮选择器
1) 用于触发聊天窗口
css Object 按钮自定义样式,如:css:{top:10%},默认无
pop Object 消息提醒气泡 [详情]

示例

ud({
    "mobile", {
        "mode": "blank",
        "color": "#307AE8",
        "pos_flag": "crb",
        "onlineText": "联系客服,在线咨询",
        "offlineText": "客服下班,请留言",
        "pop": {
            "direction": "top",
            "arrow": {
                "top": 0,
                "left": "70%"
            }
        }
    }
});

> 会话面板 - 参数说明

参数名称 类型 是否必选 说明
css Object 自定义样式,如:css:{top:10%},默认无
onToggle Function 自定义方法
参数:data.visible(true或false)},
检测当前会话面板是否打开,visible为true时则是打开状态

示例

ud({
    "panel", {
        "css": {
            "top": "0",
            "left": "0"
        },
        "onToggle": function(data) {  //面板开关时间
            if (data.visible) {
                //console.log('窗口打开');
            }
            else{
                //console.log('窗口关闭');
            }
        }
    }
});

> 消息提醒气泡 - 参数说明

参数名称 类型 是否必选 说明
css Object 自定义样式,如:css:{top:10%},默认无
direction String 气泡弹出方向,"top"(默认);"right";"left";"bottom"
offset Object 气泡位移量,{top:0,left:0},默认相对居中显示
arrow Object 气泡箭头配置,{top:0,left:0},默认相对居中显示

示例

ud({
    "pop": {
        "direction": "top",
        "arrow": {
            "top": 0,
            "left": "70%"
        }
    }
});

> 客户信息 - 参数说明

概述

网站登录用户通过web im进行聊天对话时,可以将客户信息通过链接转给Udesk,这样客服在与客户对话时,就可以直接查看客户信息。通过客户信息辅助组件也可以进一步了解此客户的订单等其他信息。

使用方法

在web im对话窗口的链接(http://xxxx.udesk.cn/im_client/)按照以下规则增加参数和加密信息,即可传输客户信息。

其中邮箱和电话号码用于客户识别,即与Udesk系统内CRM中已有数据进行比对,如果为已有客户会更新信息,如果没有匹配则会新建客户。

> 客户身份认证 - 请求参数

传递客户信息、业务记录首先需要做用户身份认证;如果是访客的话就不需要传递客户信息,也就不需要客户身份认证了。如果是客户的话,请认真参考下面参数及[signature加密算法]。 如果传递了客户身份识别, 客户身份的识别顺序: web_token -> customer_token -> c_email -> c_phone 。客户身份识别有效时间: 4天。

参数名称 类型 是否必选 说明
nonce String 随机数 随机数,动态的比静态随机数安全系数更高
timestamp String 时间戳 当前时间戳(13位毫秒)
web_token String 客户ID 客户唯一标示,推荐使用邮箱、手机号等
signature String 加密签名 [signature加密算法]

signature加密算法(三步)

1、按后面参数及顺序拼接字符,以key=value&形式: noncetimestampweb_tokenim_user_key
im_user_key获取位置【管理中心-即时通讯-网页插件-管理/添加客户信息中的KEY】

sign_str = nonce=value&timestamp=value&web_token=value&im_user_key

2、 使用 sha1 计算出签字符串

sign_str = sha1(sign_str)

3、 将字符串转换为大写

sign_str = sign_str.toUpperCase()

4、易错提醒

1、 im_user_key无需参数仅需要值即可 2、 signature字符串要转换为大写

示例:
    sign_str = "nonce=9ca6fff5a509fb887ac72cf5c92010e7&timestamp=1455675719000&web_token=test@udesk.cn&b476f9f8-5309-4d0a-a2d4-af08c4507a15";
    sign_str = sha1(sign_str);
    sign_str = sign_str.toUpperCase();

示例

ud({
    "customer": {
        "nonce": "694db2645b3f69a8",
        "signature": "315345C77C73A128CF9850EAD777F7A71D423A36",
        "timestamp": "1465878579000",
        "web_token": "newest3@udesk.cn"
    }
});

客户参数

参数名称 类型 是否必选 说明
c_name String 客户姓名
c_email String 客户邮箱唯一
c_phone String 客户电话唯一
customer_token String 客户外部标识唯一 open_api_token同一字段
c_desc String 客户描述
c_org String 公司名称
c_tags String 客户标签 传入客户标签,用逗号分隔 如:"帅气,漂亮"
c_owner String 客户负责人ID
c_vip String 'vip'(vip客户) 或者 'normal'(普通客户) 客户vip识别
c_owner_group String 客户负责组ID
c_other_emails String 客户其他邮箱列表 逗号分隔 如:"a@xxx.cn,b@xxx.cn"
c_cf_<自定义字段名称> String 客户自定义字段 客户自定义字段 如: c_cf_名字、c_cf_age、...

> 业务记录 - 请求参数

参数名称 类型 是否必选 说明
c_cn_title String 业务记录主题 传入业务记录主题
c_cn_<自定义字段名称> String 业务记录自定义字段 业务记录自定义字段 如: c_cf_名字、c_cf_age、...

示例

ud({
    "customer": {
        "c_name": "客户姓名kimi",
        "c_email": "newest3@udesk.cn",
        "c_other_emails": '11@udesk.cn,22@udesk.cn',
        "c_desc": "意向客户,潜力巨大",
        "c_org": "desc",
        "c_phone": "1100110012",
        "c_tags": "英俊,新加的",
        "c_owner_group": "62",
        "c_owner": "3",
        "c_vip": "vip",
        "c_qq": "123123",
        "c_cf_年龄": 10,
        "c_cf_爱好": "极限挑战",
        "c_cn_title":"业务记录主题",
        "c_cn_名字":"业务记录的名字",
        "nonce": "694db2645b3f69a8",
        "signature": "315345C77C73A128CF9850EAD777F7A71D423A36",
        "timestamp": "1465878579000",
        "web_token": "newest3@udesk.cn"
    }
});

链接示例

所传的参数请编码处理,否则会出现乱码!

http://xxx.udesk.cn/im_client/?c_desc=test123456789&c_email=jiangst%40udesio.com&c_phone=15888888888&echostr=hello&nonce=cdebd5d13f4d331e&signature=693140534BDDDAF002A46F0027E06244DF0B21AB&timestamp=1457696747000&web_token=42f6607e-8892-4fcf-889b-f9babf627060

> 咨询对象 - 参数说明

提供两种接入方式:url传参方式、javascript接入方式

参数说明

名称 说明
title 标题
url 跳转页的链接地址
image 显示图片
<自定义参数> 可定义多个自定义参数,可为中文

url传参方式

在所有的参数前面加前缀product_,所传的参数请编码处理,否则会出现乱码!

如:http://udeskdemo.udesk.cn/im_client/?product_title=Apple%20iPhone%207&product_url=http%3A%2F%2Fitem.jd.com%2F3133829.html%3Fcu%3Dtrue%26utm_source%E2%80%A6erm%3D9457752645_0_11333d2bdbd545f1839f020ae9b27f14&product_image=http%3A%2F%2Fimg14.360buyimg.com%2Fn1%2Fs450x450_jfs%2Ft3157%2F63%2F1645131029%2F112074%2Ff4f79169%2F57d0d44dN8cddf5c5.jpg%3Fv%3D1474635884816&product_%E4%BB%B7%E6%A0%BC=%EF%BF%A56189.00&product_%E4%BF%83%E9%94%80%E4%BF%A1%E6%81%AF=%E8%B4%AD%E4%B9%B0%E4%BA%AC%E4%B8%9C%E8%87%AA%E8%90%A5%E7%94%B5%E8%84%91%2C%E6%89%8B%E6%9C%BA%2C%E6%95%B0%E7%A0%81%E5%93%81%E7%B1%BB%E6%8C%87%E5%AE%9A%E4%BA%A7%E5%93%81%2C%E5%AE%9E%E9%99%85%E4%B8%8B%E5%8D%95%E7%BB%93%E7%AE%97%E9%87%91%E9%A2%9D%E6%BB%A1199%E5%85%83%2C%E8%BF%94%E4%BA%AC%E4%B8%9C%E8%87%AA%E8%90%A5%E5%A4%A7%E9%97%B8%E8%9F%B9%E4%B8%9C%E5%88%B8%E4%B8%80%E5%BC%A0.

javascript接入方式

ud({
    product: {
        title: "Apple iPhone 7",
        url: "http://item.jd.com/3133829.html?cu=true&utm_source…erm=9457752645_0_11333d2bdbd545f1839f020ae9b27f14",
        image: "http://img14.360buyimg.com/n1/s450x450_jfs/t3157/63/1645131029/112074/f4f79169/57d0d44dN8cddf5c5.jpg",
        "价格": "¥6189.00",
        "促销价": "¥6188.00"
   }
});

> 配置客户端多语言 -详情

从多语言配置中查找已经配置的多语言语言码

多语言功能请单独联系Udesk开通

管理 -> 账户设置-> 多语言支持

语言名称 文件名称 语言码 更新日期 操作
English reocar_language_translation(en-us).xlsx en-us 2017/08/23 14:30 下载文件 上传选择文件 更新

选取配置的语言码 en-us 作为 language的参数。如果需要使用法语,需要先配置法语的多语言,然后使用多语言支持列表中的法语配置记录的语言码

zh-cn(简体中文)已经是系统默认,可以直接使用,不需要在多语言支持中配置

如果language传了一个多语言支持列表中没有配置的语言码参数,会使用默认的简体中文

前端的静态资源中的显示内容现在支持简体中文和English,不支持自定义语言翻译。如果需要支持更多的语言,请联系我们

多语言语言码配置规定

语言码只能从以下列表中选择:

如果想配置的多语言语言码不在下面列表中, 请联系Udesk

语言名称 语言码
阿拉伯语 ar
English en-us
西班牙语 es
法语 fr
日语 ja
朝鲜语/韩语 ko
泰语 th
印度尼西亚语 id
繁体中文 zh-TW
葡萄牙语 pt
俄罗斯语 ru

方法说明

方法名称 参数 说明
hidePanel 手动隐藏会话面板,如:ud.hidePanel()
showPanel 手动打开会话面板,如:ud.showPanel()
init 手动初始化,如:ud.init()

注意:ud.init()方法只有当manualInit设置为true时才会生效,否则无效,当manualInit属性为true时,嵌入的代码不会自动初始化,需要手动初始化,否则代码不生效。手动初始化方法ud.init()方法必须放在onReady事件回调的内部才能触发。

示例

ud.hidePanel();//初始化完成后才生效, 仅在网页内嵌模式生效
ud.showPanel();
ud.init(); //manualInit为true时才会生效

事件说明

参数名称 类型 是否必需 说明
onReady Function 监听事件,无参数 Udesk IM插件初始化完成事件回调
onUnread Function 监听事件,参数:data:{count:1 //未读消息数} 未读消息事件回调

示例

ud({
    "onReady": function() {
        console.log('初始化完成');
    },
    "onUnread": function(data) {
        console.log('未读消息数'+data.count);
    }
});

窗口设置 - 信息区自定义URL

当使用udesk网页插件,并且在网页插件的窗口设置中配置了自定义URL时,可以在配置的页面内给Udesk客服/机器人发送消息.

基本用法

自定义URL 页面通过 postMessage 和父级页面通信, 需遵循特定的消息格式

客服聊天界面: 可以发送文本消息和商品消息

机器人聊天界面: 只支持发送文本消息

当前窗口网页链接传入自定义的iframe

窗口会将当前网页链接的参数传入自定义URL的iframe.(其中这四个参数cur_url/cur_title/pre_url/src_url不传).

参数说明

参数名称 类型 是否必填 说明
method String 'sendMsg' 方法名称,目前只支持sendMsg
type String 'text' or 'product' 消息类型: 文本消息商品消息
content String|Object 消息内容

示例

1. 文本消息

    var data = JSON.stringify({
            method: "sendMsg",   // 固定method
            type: "text",        // 固定type
            content:  “xxx”      // 需要发送的消息
        });
    var origin = "*";
    window.parent.postMessage(data, origin);

2. 商品消息 参数详情

    var data = JSON.stringify({
            method: "sendMsg",      // 固定method
            type: "product",        // 固定type
            content: {              // 商品消息格式
                name: "Apple iPhone X (A1903) 64GB 深空灰色 移动联通4G手机",
                url: "https://item.jd.com/6748052.html",
                imgUrl: "http://img12.360buyimg.com/n1/s450x450_jfs/t10675/253/1344769770/66891/92d54ca4/59df2e7fN86c99a27.jpg",
                params: [{
                    text: "¥6999.00",
                    color: "#FF0000",
                    fold: false,
                    break: false,
                    size: 12
                }, {
                    text: "满1999元另加30元"
                }]
            }
        });
    var origin = "*";
    window.parent.postMessage(data, origin);

注意事项

  1. 请限制发送频率
  2. 注意消息格式