# 在线客服

# 1、接口声明

在调用接口时必须在https请求的header中携带"token"参数。

token是智齿客服接口开放平台全局唯一的接口调用凭据。
开发者在调用各业务接口时都需使用token,开发者需要进行妥善保存。token的存储至少要保留32个字符空间。token的有效期目前为24个小时,需定时刷新,或根据接口返回的token失效提示,进行重新获取。请求token接口,无论token是否存在,都会返回新的token,并重置token的过期时间(目前24小时)。

token使用方式说明:
1、开发者需要统一获取和管理token,在调用智齿客服各个业务开放接 口时都应该使用同一个的token,不应该每个业务都刷新获取新的 token,否则容易导致token失效,影响接口的正常调用;
2、目前token的有效期通过返回的expire_in来传达,目前是86400 秒之内的值。开发者需要根据这个有效时间提前去刷新新token。
3、开发者需要根据接口返回的token失效提示,进行重新获取token。

# 2、接口调用

# 2.1、获取访问token编码

接口说明:

获取API开放接口token,此token仅适用于智齿开放平台 5.0版本全部API接口 。API接口中的参数 appid, app_key 请联系智齿售后人员获取。

请求方式:

GET

请求地址:

https://www.sobot.com/api/get_token

请求参数:

参数 类型 必填 名称 备注
appid String 接口凭证Id 第三方用户接口调用唯一凭证id
create_time String 时间戳 时间戳,秒,例如 2019-09-25 15:49:33 的时间戳1569397773
sign String 签名 md5(appid+create_time+app_key) sign签名,app_key为密钥

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 必填 名称 备注
token String token编码
expires_in String 凭证有效时间 单位:秒

时间戳转换参考工具:

http://tool.chinaz.com/Tools/unixtime.aspx

sign签名生成示例:

例如,appid = "1"; create_time="1569397773"; app_key="2"

sign = Md5("115693977732") 为 258eec3118705112b2c53dc8043d4d34。

请求示例:

curl https://www.sobot.com/api/get_token?appid=1&create_time=1569397773&sign=258eec3118705112b2c53dc8043d4d34

返回示例:

{
    "item": {
        "token": "4ac37cb2e9c740dba4b75a34d5358802",
        "expires_in": "86400"
    },
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.2、请求人工客服

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口以用户的身份来发起用户和客服之间的会话请求,并建立会话。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/chat_connect

请求参数:

参数 类型 必填 名称
partnerid String 企业自己的用户id,可自行传值
source String 客户来源,0-pc,1-微信,2-sdk,3-微博,4-h5
agentid String 指定客服的id
tran_flag String 是否必须转入指定客服,1-是,0-否
groupid String 指定技能组
params String(json) 自定义参数
user_tels String 用户电话
user_emails String 用户邮箱
user_name String 用户真实姓名
user_nick String 用户昵称
user_img String 用户头像

返回参数:

参数 类型 必填 名称
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称
status String 状态:-1.重复请求,拒绝处理,0.排队,1.成功 2.无客服 3.在黑名单
agent_name String 客服姓名
agent_face String 客服头像
agentid String 客服id
visitorid String 用户id
cid String 会话id
count String 排队位置

请求示例:

curl https://www.sobot.com/api/chat/5/user/chat_connect 
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	 
    "partnerid" : "123",
    "source" : "0",
    "agentid " : "61673ee8d98d4282a95cdad38ffd5f5b ",
    "tran_flag" : "1",
    "params" : "{\"name\":\"lxl\",\"age\":18}",
    "user_tels" : "13778967890;13278907890",
    "user_emails" : "xiaoming@163.com; xiaoming2@163.com",
    "user_img":"https://sobot-www.oss-cn-beijing.aliyuncs.com/001915.JPG",
    "user_name" : "小明"
    }'

返回示例:

{
  "item": {
    "status": "1",
    "visitorid" :"fdd445a5b10f303297752dc3625db648",
    "agent_name" :"在线客服", 
    "agent_face":"https://sobot-www.oss-cn-beijing.aliyuncs.com/6112512332.PNG", 
    "agentid":"61673ee8d98d4282a95cdad38ffd5f5b", 
    "cid":"eca9155a77384d64bb64a132e8459b7e"
  },
  "ret_code": "000000",
  "ret_msg": "成功"
}

# 2.3、客户咨询客服

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口以用户的身份给客服发送消息。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/chat_send

请求参数:

参数 类型 必填 名称 备注
partnerid String 企业自己的用户id,可自行传值
content String 用户问题
msg_type String 消息类型 (text,image,voice,默认为text纯文本,如果为image和voice的时候,content传递图片地址或者音频地址,其中音频支持mp3,wav两种格式)

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
status String 状态:1.成功 2.用户没有跟客服建立连接

请求示例:

curl https://www.sobot.com/api/chat/5/user/chat_send
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d ' {
    "partnerid": "123",
    "content": "https://bbs.sangfor.com.cn/data/attachment/sfchat/image/20687/1571984960.png",
    "msg_type": "image"
} '

返回示例:

{
  "item": {
    "status": "1"
  },
  "ret_code": "000000",
  "ret_msg": "成功"
}

# 2.4、客服消息推送

接口说明:

接口类型:回调型接口

接口作用:智齿将客服发送给用户的消息推送至企业预先配置好的回调地址上。

参数说明:

参数 类型 名称 备注
sys_code String 系统编码 2:在线业务
type String 消息类型 chat_user_msg:用户接收消息
is_encrypt String 是否加密,true:加密false:不加密
content Object 消息内容 详见下表

消息内容:

参数 类型 名称 备注
msg_code String 消息编码 200:客户接入客服 201:客户收到排队位置变更 202:客户收到客服发送的消息 204:客户离线 209:客户收到客服邀请评价的消息
msg_id String 消息id
msg_type String 消息类型 text:文本(包含html标签)image:图片
msg String 消息内容
agentid String 客服id
agent_nick String 客服昵称
agent_face String 客服头像
partnerid String 客户对接id
params String 客户对接自定义字段
cid String 会话id

请求方式:

POST

类型:

1)用户接入会话:

{
    "sys_code":"2",
    "type":"chat_user_msg",
    "is_encrypt":"false",
    "content":{
        "cid":"a3afd241d1064780a508cbf644fc93bd",
        "agent_name":"在线客服LS186",
        "msgid":"d25f2bfe4f8f4573af5751f6ab61ea70",
        "agent_face":"https://sobot-test.oss-cn-beijing.aliyuncs.com/co2.PNG",
        "partnerid":"222",
        "msg_code":"200",
        "params":{
            "name":"xiaoming",
            "age":18
        }
    }
}

2)用户收到排队位置变更:

{
    "sys_code":"2",
    "type":"chat_user_msg",
    "is_encrypt":"false",
    "content":{
        "cid":"a3afd241d1064780a508cbf644fc93bd",
        "msg_code":"201",
        "count":"3",
        "msgid":"5646d04350e84f689ca855153c58c0f9",
        "partnerid":"222",
        "params":"{'name':'xiaoming','age': 18}"
    }
}

3)用户收到客服发送的消息:

{
    "sys_code":"2",
    "type":"chat_user_msg",
    "isEncrypt":"false",
    "content":{
        "cid":"a3afd241d1064780a508cbf644fc93bd",
        "msg":"222",
        "agent_name":"在线客服LS186",
        "msgid":"ab48f1e755ac766d8732501a3ef1a1161573465172716",
        "msg_type":"text",
        "agent_face":"https://sobot-test.oss-cn-beijing.aliyuncs.com/co12332.PNG",
        "partnerid":"222",
        "msg_code":"202",
        "params":""
    }
}

4)客户离线

{
    "sys_code":"2",
    "type":"chat_user_msg",
    "is_encrypt":"false",
    "content":{
        "cid":"a3afd241d1064780a508cbf644fc93bd",
        "msg_code":"204",
        "msgid":"eda5990841fc4f42a8a1ea5ef731a0c6",
        "partnerid":"222",
        "params":""
    }
}

5)客户收到客服邀请评价的消息

{
    "sys_code":"2",
    "type":"chat_user_msg",
    "is_encrypt":"false",
    "content":{
        "agentid":"61673ee8d98d4282a95cdad38ffd5f5b",
        "msg_code":"209",
        "agent_name":"在线客服LS186",
        "msgid":"68bab5d926334703a8a8c790aa99dd03",
        "partnerid":"222",
        "params":{
            "name":"xiaoming",
            "age":18
        },
        "cid":"83766ca85b3a4159b05b00b82dc12197"
    }
}

# 2.5、客户评价

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口执行用户对会话进行满意度评价。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/comment

请求参数:

参数 类型 必填 名称 备注
partnerid String 企业自己的用户id,可自行传值
type String 评价类型:0:评价机器人,1:评价人工
solved String 评价结果:0:未解决,1:已解决
score String 人工评价分数(1,2,3,4,5)
tag String 评价标签,多个用逗号分隔
remark String 评价内容
comment_type String 评价类型:0-邀请评价,1-主动评价

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
status String 状态:0.失败,1.成功,2-已评价,3-无咨询,不能评价
cid String 会话ID

请求示例:

curl https://www.sobot.com/api/chat/5/user/comment 
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{
    "partnerid" : "123", 
    "type" : "1", 
    "solved" : "1"
   }'

返回示例:

{
"item": {
    "status":"1",
    "cid":" eca9155a77384d64bb64a132e8459b7e" 
    },
"ret_code": "000000",
"ret_msg": "成功"
}

# 2.6、客户结束会话

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来结束某个用户当前的会话。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/out

请求参数:

参数 类型 必填 名称 备注
partnerid 字符串 企业自己的用户id,可自行传值

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
status String 状态:1.成功 整型

请求示例:

curl https://www.sobot.com/api/chat/5/user/out
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
    "partnerid" : "123"
}'

返回示例:

{
    "item": {
        "status":"1"
    },
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.7、查询离线消息数据

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来获取会话已经结束后,客服发送给用户的消息(即离线消息)。开放平台接口对接的用户,由于所有消息都会推送到消息地址中,没有离线消息数据。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/offline_msg_data

请求参数:

参数 类型 必填 名称 备注
visitorid String 访客id

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
size String 离线消息数
msg_data List 客服列表及对应客服发送的消息列表

msg_data对象:

参数 类型 名称 备注
sender String 发送者id
sender_name String 发送者昵称
send_face String 发送者头像
msg_list List 消息列表

msg_list对象:

参数 类型 名称 备注
cid String 会话id
msg String 消息体
ts String 发送消息时间

请求示例:

curl https://www.sobot.com/api/chat/5/user/offline_msg_data
-X POST 
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
"visitorid" : "xx"
}'

返回示例:

{
    "item": {
        "size": 2,
        "msg_data":[
        		 {
       		 "sender ": " 61673ee8d98d4282a95cdad38ffd5f5b",
        	 "sender_name": "在线客服",
  			 "sender_face":" https://sobot-www.oss-cn-beijing.aliyuncs.com/console/2512332.PNG",
       		 "msg_list": [
         			 {
                        "cid": "c36d04f18b4e48eaa88e7a5c93212a0a",
                        "msg": "111",
                        "ts": "2019-10-31 19:13:57"
                    },
                    {
                        "cid": "c36d04f18b4e48eaa88e7a5c93212a0a",
                        "msg": "222",
                        "ts": "2019-10-31 19:13:59"
                    }
       			 ]
     		 }
   		 ]
    },
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.8、查询客户会话列表

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来获取某个用户在系统中的会话记录列表(cid列表)。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/query_cids

请求参数:

参数 类型 必填 名称 备注
visitorid String 访客id visitorid与partnerid选择其一
partnerid String 企业自己的用户id,可自行传值 与from参数配套使用
from Integer 来源:0-开放平台,1-pc/h5/sdk,2-微信
start_time String 开始时间 unixtime ms,例如:"1539153409792"
end_time String 结束时间 unixtime ms,例如:"1539153409792"

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象:

参数 类型 名称 备注
cid String 会话ID
start_date_time String 会话时间,毫秒
visitorid String

请求示例:

curl https://www.sobot.com/api/chat/5/user/query_cids
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
       "visitorid" : "xx"
}'

返回示例:

{
    "items": [
        {
            "cid": "825a57e755a240559e03deec267e6463",
            "start_date_time": 1568603119126,
            "visitorid": "7f27b999bbe94274ab1a738568aba137"
        },
        {
            "cid": "1874cbc483b64d4b9f1b7f06de083638",
            "start_date_time": 1568613840540,
            "visitorid": "7f27b999bbe94274ab1a738568aba137"
        }    
],
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.9、查询客户会话记录

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来获取某条会话的详细会话记录。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/get_detail_by_cid

请求参数:

参数 类型 必填 名称 备注
cid String 会话id
partnerid String 企业自己的用户id-供开放平台用户使用
from Integer 来源:0-开放平台,1-pc/h5/sdk
visitorid String 智齿平台用户id-所有来源用户都可使用
name_flag Integer 客服名字类型:0.昵称(默认) 1.真实姓名

说明:1)cid,visitorid,partnerid+from为三种查询模式,优先级为:cid>visitorid>partnerid+from;

2)传入visitorid或者partnerid+from时,表示查询用户的最后一次会话记录。

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象:

参数 类型 名称 备注
sender_name String 发送者昵称
sender_type String 发送者类型 0-用户,1-机器人,2-客服
sender_face String 发送者头像
receiver_name String 接收者昵称
receiver_type String 接收者类型 0-用户,1-机器人,2-客服
receiver_face String 接收者头像
ts String 发送时间 格式:yyyy-MM-dd HH:mm:ss
t String 发送时间 格式:毫秒级时间戳
msg String 会话消息
msg_type Integer 消息类型:0-文本,1-图片,2-音频,3-富文本
cid String 会话ID

请求示例:

curl https://www.sobot.com/api/chat/5/user/get_detail_by_cid
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
    "cid" : "49142902cfa74f2d9af8e7c1b546221d",
    "name_flag" : "1"
    }'

返回示例:

 {
    "items": [{
            "cid": "49142902cfa74f2d9af8e7c1b546221d",
            "msg":"<img src='http://bbs.sangfor.com.cn/data/attachment/sfchat/image/201910/154687/1571984960.png' class='webchat_img_upload upNowImg uploadedFile' />",
            "msg_type": 1,
            "msgid": "ab221eb4fbde4ea0b9fa728448470503",
            "receiver": "61673ee8d98d4282a95cdad38ffd5f5b",
            "receiver_name": "在线客服",
            "receiver_type": 2,
            "sender": "fdd445a5b10f303297752dc3625db648",
                "sender_face": "https://sobot-www.oss-cn-beijing.aliyuncs.com/console/7e20834c439748c780ca9648ca6c0cde/userImage/2016120715001915.JPG",
            "sender_name": "小明",
            "sender_type": 0,
            "t": "1572514382820",
            "ts": "2019-10-31 17:33:02"            
        }],
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.10、查询客服上下班时间

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来获取某个在线客服组当前是否处于系统设置的上班时间或下 班时间。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/admin_is_work

请求参数:

参数 类型 必填 名称 备注
groupid String 技能组id

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
is_work String 上下班状态:true-上班;false-下班

请求示例:

curl https://www.sobot.com/api/chat/5/user/admin_is_work
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
    "groupid" : "1d89fad9e31d4498b1196f7580666e52"
    }'

返回示例:

{
    "item": {
        "is_work": "true"

    },
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.11、查询客服实时数据

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来获取当前登录的在线客服的列表以及状态等信息。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/get_once_data

请求参数:无

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
admin_list List 在线客服列表,详见下文
admin_size String 在线客服数量
online_user_size String 在线用户数量
wait_user_size String 排队用户数量
robot_user_size String 与机器人会话数量

admin_list对象:

参数 类型 名称 备注
agentid String 客服id
group_name List 客服所在技能组名称列表
groupid List 客服所在技能组id列表
count String 客服实时接待用户数量
agent_email String 客服邮箱
status String 客服状态(1-在线,2-忙碌)
status_code Integer 自定义状态:3.小休 4.培训 5.会议 6.用餐 7.活动
agent_name String 客服姓名
agent_face String 客服头像
remark String 客服备注
agent_nick String 客服昵称
max_count String 客服最大接待量
status_time String 状态持续时长 格式:hh:mm:ss

请求示例:

curl https://www.sobot.com/api/chat/5/user/get_once_data
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 

返回示例:

{
    "item": {
        "wait_user_size": 0,
        "admin_size": 1,
        "online_user_size": 0,
        "robot_user_size": 0,
        "admin_list": [
            {
                "agentid": "61673ee8d98d4282a95cdad38ffd5f5b",
                "status_code": 0,
                "agent_name": "真是改了名字了",
                "agent_email": "123456@123.com",
                "group_name": [
                    "销售",
                    "售后",
                    "售前"
                ],
                "groupid": [
                    "c4a3a9b8bc5742079d57d154ef2e2cc2",
                    "ef06c796d2b64218afc511dab1cd1283",
                    "a457f4dfe92842f8a11d1616c1c58dc1"
                ],
                "count": 0,
                "agent_face": "https://sobot-www.oss-cn-beijing.aliyuncs.com/console/7e2512332.PNG",
                "remark": "hello",
                "max_count": 10,
                "service_no": "1",
                "status_time": "06:53:56",
                "agent_nick": "在线客服",
                "status": 1
            }
        ]
    },
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.12、查询在线技能组列表

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来查询当前系统下所有在线客服技能组的详情。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/query_group

请求参数:无

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象:

参数 类型 名称 备注
groupid String 技能组id
group_name String 技能组名称
create_time String 创建时间(秒级时间戳)

请求示例:

curl https://www.sobot.com/api/chat/5/user/query_group
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 

返回示例:

 {
    "items": [{
        "groupid" : "c4a3a9b8bc5742079d57d154ef2e2cc2",
        "group_name" : "售前",
        "create_time" : "1540176885"
    }],
    "ret_code": "000000",
    "ret_msg": "成功"
}

# 2.13、查询在线客服列表

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来查询当前系统下所有在线客服的详情。

请求方式:

POST

请求地址:

https://www.sobot.com/api/chat/5/user/query_agent

请求参数:无

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
items List 对象列表

items对象:

参数 类型 名称 备注
agentid String 客服id
group_name List 客服所在技能组名称列表
groupid List 客服所在技能组id列表
agent_email String 客服邮箱
agent_name String 客服姓名
role_name String 角色
agent_no String 客服工号
agent_status String 客服状态
create_time String 创建时间(yyyy-MM-dd)
department_name String 部门名称

请求示例:

curl https://www.sobot.com/api/chat/5/user/query_agent
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 

返回示例:

{
    "agent_email": "123456@123.com",
    "agent_name": "在线客服",
    "agent_no": "1",
    "agent_status": "启用",
    "agentid": "61673ee8d98d4282a95cdad38ffd5f5b",
    "create_time": "2016-04-19",
    "department_name": "总公司",
    "group_name":  [
            "销售",
            "售后",
            "售前"
        ],
    "groupid": [
        "c4a3a9b8bc5742079d57d154ef2e2cc2",
        "ef06c796d2b64218afc511dab1cd1283",
        "a457f4dfe92842f8a11d1616c1c58dc1"
    ],
    "role_name": "超级管理员"
}

# 2.14、查询服务总结记录

接口说明:

接口类型:主动调用接口

接口作用:可通过调用该接口来获取服务总结记录。

请求方式:

POST

请求地址:

https://www.sobot.com/api/wb/5/data/query_summary

请求参数:

参数 类型 必填 名称 备注
cid 字符串 会话id cid

返回参数:

参数 类型 必填 名称 备注
ret_code String 返回编码
ret_msg String 返回信息
item Object 返回对象

item对象:

参数 类型 名称 备注
summary_flag String 总结状态,1-已总结,0-未总结
update_time String 总结时间
operation_name String 业务单元
req_type_name String 业务类型
question_status String 解决状态,1-已解决,0-未解决
question_description String 备注说明
invalid_session String 无效会话,1-无效,0-有效
fields List 自定义字段列表
summary_staff_name String 总结客服
cid String 会话id

fields对象:

参数 类型 名称 备注
fieldid String 字段id
field_name String 字段名称
field_value String 字段值

请求示例:

curl https://www.sobot.com/api/wb/5/data/query_summary
-X POST 
-H 'content-type:application/json'
-H 'token: 4ac37cb2e9c740dba4b75a34d5358802' 
-d '{	  
"cid": "xx"
}'

返回示例:

{
    "item": {
            "cid": "3cd40201989943df8cd1ed845efcb043",
            "summary_flag": "1",
            "operation_name": "业务单元",
            "req_type_name": "业务类型1,业务类型2",
            "summary_staff_name": "客服1",
            "question_status": "1",
            "question_description": "问题描述",
            "fields": [
            {
            "fieldid": "28f002c873c344d9a8f9b3606830dfbb",
            "field_name": "业务单元字段1",
            "field_value": "值1"
            },
            {
            "fieldid": "9b9086c5bed84016af5adf273d41110e",
            "field_name": "业务单元字段2",
            "field_value": "值2"
            }
            ],
            "invalid_session": "0",
            "update_time": "1554716281854"
        },
    "ret_code": "000000",
    "ret_msg": "操作成功"
}

# 2.15、单点登录接口

更新说明:

接口已经移动至开发指南\通用模块\单点登录中。

# 3、在线消息转发

该功能消息格式为json格式;实时消息推送配置将在次日凌晨零点开始生效。同公司同类型的数据,缓存20条打包发送一次,不足20条时每1秒打包发送一次。

实时消息推送需要客户提供数据接收接口,例如 https://xxxxxxx.xxxxxx.com/sobot/message,所有的类型的数据使用相同的地址。

消息转发接口,增加可以加密后再传递,可以联系您的客户经理,设置开通后,可以在消息转发时header中增加三个参数:时间戳(取服务器时间)、随机码、sign(MD5加密,32位 小写));客户取到参数后解码对比,正确接收数据,错误时返回错误码。

header中参数

参数 类型 备注
X-Log-TimeStamp String 时间戳(取服务器时间,毫秒)
X-Log-RandomCode String 随机码)
X-Log-Sign String sign签名,对companyId,时间戳(取服务器时间),随机码 ,appKey(配置消息转发时使用的密钥)按照顺序进行字符串拼接,使用MD5摘要算法(32位小写)所得值

请求示例

curl https://xxxxxxx.xxxxxx.com/sobot/message
-X POST 
-H 'X-Log-TimeStamp: 1609224926723'
-H 'X-Log-RandomCode: 635'
-H 'X-Log-Sign: 9ba80f40bc5e6fd404648ea15aa4f7fa'

# 3.1在线会话消息

# 3.1.1 content对象

参数 类型 必填 名称 备注
companyid String 公司Id 适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
cid String 会话id
source String 用户来源 0 pc;1 微信;2 sdk;3 微博;4 移动网站;9 企业微信;10 微信小程序
start_time String 开始时间 unixtime ms,例如:"1539153409792"
end_time String 结束时间 unixtime ms,例如:"1539153409792"
first_response_time String 首次响应时间 unixtime ms,例如:"1539153409792"
transfer_tohuman_time String 机器人转人工时间 unixtime ms,例如:"1539153409792"
conversation_duration String 会话时长 单位:毫秒
staff_emails String 最后接待客服Email
staff_name String 最后接待客服姓名
consult_robot_msg_count String 咨询机器人消息数
robot_reply_msg_count String 机器人回复数
consult_staff_msg_count String 咨询人工消息数
staff_reply_msg_count String 人工回复数
transfer_human_succ_flag String 转人工是否成功 1-是;0-否
queue_time String 排队时长 单位:毫秒
session_queue_state String 排队状态 1-未排队接通;2-排队成功;3-排队离开
ip String 访问IP 格式: "255.255.255.255"
area String 地域
os String 终端 1 Windows XP;2 Windows 7;3 Windows 8;4 Windows Vista;5 Windows 其他;6 Linux;7 macOS;8 Android;9 iOS;11 Windows 2000;12 Windows 10 ;其他 其他
visitorid String 用户ID
partnerid String 合作方用户ID
lastgroupid String 最后接待客户组Id
lastgroup_name String 最后接待客户组名称
offline_type String 会话结束方式 1 客服离线,2 客户被客服移除 3 客户被客服加入黑名单 4 客户会话超时 5 客户关闭了聊天页面 6 客户打开新的页面
human_valid_flag String 是否是人工有效会话 1 是 0否
human_invalid_flag String 是否是人工无效会话 1 是 0否
human_invalid_recep_flag String 是否是人工无效接待 1 是 0否
human_valid_recep_flag String 是否是人工有效接待 1 是 0否
human_recep_flag String 是否是人工接待 1 是 0否
robot_invalid_flag String 是否是机器人无效会话 1 是 0否
robot_valid_flag String 是否是机器人有效会话 1 是 0否
province_name String 省份名称
city_name String 城市名称
access_human_time String 接入人工时间
robotid String 机器人id
robot_alias String 机器人别名 机器人的对接参数,优先级高于robotid,目前仅支持APP渠道
robot_name String 机器人昵称
staffids String 所有接待客服Id,以逗号分割;
invite_evaluation_flags String 客服是否发起邀评,对应接待客服Id的顺序 ,1 发起过邀评,0 未发起邀评
response_duration Long 总响应时长 毫秒
response_count Int 总响应次数
response_avg String 平均响应时长=总响应时长/总响应次数
session_human_duration String 人工接待时长
asHuman_interactive_count String 人工交互会话数
channel_flag String 子渠道Id
channel_name String 子渠道名称
search_engine String 搜索来源 1、百度自然搜索;2、百度付费搜索;3、360搜索;4、sougou;5、神马;6、必应;7、谷歌;8、其他搜索引擎 ;9、直接访问; 10、外部链接;11、百度未知访问
land_page_url String 着陆页url
land_page_title String 着陆页标题
conversation_page_url String 发起会话页url
conversation_page_title String 发起会话页标题
search_word String 搜索词

注:唯一主键 cid,各表通过cid关联,表示同一个会话

# 3.1.2 请求参数

参数 类型 必填 名称 备注
sys_code String 产品编码 21
type String 消息类型 conversation
content List 消息内容

# 3.1.3 请求报文样例

{ 
  "sys_code":"21",
    "type":"conversation",
    "content":[
        {
            "companyid":"5cc2c708202d4defaf72d4bcac362a55",
            "cid":"86937e82ae244ad59aeefe41af731079",
            "source":"2",
            "start_time":"1468826506677",
            "partnerid":"1907281202433341",
            "end_time":"1468827002400",
            "first_response_time":"1468827002400",
            "transfer_tohuman_time":"1468826506677",
            "conversation_duration":"495723",
            "staff_emails":"11122221@foxmail.com",
            "staff_name":"路人丁",
            "consult_robot_msg_count":"3",
            "robot_reply_msg_count":"20",
            "consult_staff_msg_count":"0",
            "staff_reply_msg_count":"0",
            "transfer_human_succ_flag":"1",
            "queue_time":"0",
            "session_queue_state":"2",
            "ip":"60.18.150.38",
            "area":"辽宁",
            "os":"8",
            "visitorid":"837213545777846",
            "lastgroupid":"35980200f279438b952f8dc3d5731f85",
            "lastgroup_name":"客服组",
            "human_valid_flag":"1",
            "human_invalid_flag":"0",
            "human_invalid_recep_flag":"0",
            "human_valid_recep_flag":"0",
            "human_recep_flag":"1",
            "robot_invalid_flag":"0",
            "robot_valid_flag":"1",
            "offline_type":"1",
            "access_human_time":"1584806400000",
            "robotid": "1234",
            "robot_alias": "test_alias",
            "robot_name": "机器人小明",
            "staffids":"3695089d031c409380073081aaa73c7d,733e9edabb5c4158b095198aec58a890,3ff11cb243b540f78f8274f84b289920",
            "invite_evaluation_flags":"0,1,1",
            "channel_flag": "d720fe0e97ac427183c65b59f82c061f",
            "channel_name": "Android - 正式",
            "response_duration": "0",
            "response_count": "0",
            "response_avg": "0",
            "session_human_duration": "0",
            "asHuman_interactive_count": "0",
            "search_engine": "1",
            "land_page_url": "http://www.sobot.com",
            "land_page_title": "【官网】智齿科技-智齿客服 | 在线客服系统_云呼叫中心_智能客服机器人_智能外呼",
            "conversation_page_url": "http://www.sobot.com", 
            "conversation_page_title": "【官网】智齿科技-智齿客服 | 在线客服系统_云呼叫中心_智能客服机器人_智能外呼",
            "search_word": "客服"
        }
    ]
}

# 3.2在线评价消息

# 3.2.1 content对象

参数 类型 必填 名称 备注
companyid String 公司ID 适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
staffid String 客服ID
source String 用户来源 0-pc;1-微信;2-sdk;3-微博;4-移动网站;9-企业微信;10-微信小程序
admin_name String 评价对象 可能是客服或机器人
is_robot String 是否是机器人 1-是机器人,0-是人工客服
remark String 备注信息
tag String 评价标签
score String 5星评分 最高5星,均为正整数
nps_score String 10分评分 最高10分,均为整数
visitorid String 访客ID
date_time String 时间 unixtime ms,例如 1539153409792
cid String 会话ID 会话的唯一标识
comment_type String 评价类型 0-邀请评价,1-主动评价
solved String 标记是否解决 1-解决,0-未解决,-1 未开启

注:唯一主键(cid+is_robot)

# 3.2.2 请求参数

参数 类型 必填 名称 备注
sys_code String 产品编码 21
type String 消息类型 evaluation
content List 消息内容

# 3.2.3 请求报文样例

{
    "sys_code":"21",
    "type":"evaluation",
    "content":[
        {
            "companyid":"5cc2c708202d4defaf72d4bcac362a55",
            "staffid":"9517",
            "source":"10",
            "admin_name":"",
            "is_robot":"1",
            "remark":"意向用户可跟",
            "tag":"答非所问,问题不能回答",
            "score":"2",
            "visitorid":"97b31cba87e04dcdafe0ebb60248ecf4",
            "date_time":"1468340203266",
            "cid":"9ae05bc279544b68895cd86b12e418e0",
            "comment_type":"1",
            "solved":"1"
        }
    ]
}

# 3.3在线访客信息

# 3.3.1content对象

参数 类型 必填 名称 备注
companyid String 公司ID 适用一个公司多个超管帐号或者多个分公司需要分别统计的情况。
userid String 访客ID
img String 访客头像
nick String 访客昵称 访客昵称
source String 访客来源 0 桌面网站;1 微信公众号;2 APP;3 微博;4 移动网站;9 企业微信;10 微信小程序;12 百度营销;17 微信客服
enterprise_name String 公司名称 默认值为空字符串
user_tels String 联系电话 联系电话,如多个号码采用英文逗号","隔开
user_emails String 电子邮箱 电子邮箱,如多个邮箱采用英文逗号","隔开
qq String QQ号码
partnerid String 合作方用户ID
user_name String 访客姓名
province_name String 省份
city_name String 市名称 默认值为空字符串
area_name String 县/区名称 默认值为空字符串
remark String 备注信息
serviceid String 客服ID 最后接待客服
cid String 会话ID
params String 动态参数 jsonString,对接时由客户传过来
summary_params String 服务总结相关参数 jsonString,对接由客户传过来

注:唯一主键 userid

# 3.3.2 请求参数

参数 类型 必填 名称 备注
sys_code String 产品编码 21
type String 消息类型 user
content List 消息内容

# 3.3.3 请求报文样例

{
    "type":"user",
    "sys_code":"21",
    "content":[
        {
            "companyid":"5cc2c708202d4defaf72d4bcac362a55",
            "userid":"837213545777846",
            "img":"https://img.sobot.com/console/common/face/user.png", 
            "nick":"招商王", 
            "source":"10", 
            "enterprise_name":"",
            "user_tels":"13545777846",
            "user_emails":"506003007@qq.com",
            "qq":"784383358",
            "partnerid":"13545777846",
            "user_name":"孙盼",
            "province_name":"山东", 
            "city_name":"", 
            "area_name":"",
            "remark":"",
            "params":{
                "KUID":"MTU2NjY0MzE1NTAwMDA3MTAz",
                "cookie":"88a484e052f1455a8706213cd41c4c94"
            },
            "serviceid":"ea6f8d1a5e8846fd8dfce4ab7057c45c", 
            "cid":"86937e82ae244ad59aeefe41af731079",
        }
    ]
}

# 3.4在线客户信息

# 3.4.1content对象

参数 类型 必填 名称 备注
companyid String 公司ID 适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
userid String 用户ID
img String 用户头像
nick String 用户昵称 用户昵称
source String 用户来源 0 pc;1 微信;2 sdk;3 微博;4 移动网站;9 企业微信;10 微信小程序
enterprise_name String 公司名称 默认值为空字符串
user_tels String 用户联系电话 默认值为空字符串
user_emails String 用户邮箱 默认值为空字符串,此参数可能会采用英文逗号","隔开
user_name String 用户真实姓名 默认值为空字符串
qq String 用户QQ 默认值为空字符串
province_name String 省份
city_name String 市名称 默认值为空字符串
area_name String 县/区名称 默认值为空字符串
remark String 备注 默认值为空字符串
visitorids String 访客ID 默认值为空字符串
service_no String 客服工号 默认值为空字符串
serviceid String 客服ID
cid String 会话ID
result_list List 自定义字段

# 3.4.2 请求参数

参数 类型 必填 名称 备注
sys_code String 产品编码 21
type String 消息类型 userinfo
content List 消息内容

# 3.4.3 请求报文样例

{
    "sys_code":"21",
    "type":"userinfo",
    "content":[
        {
            "companyid":"5cc2c708202d4defaf72d4bcac362a55",
            "userid":"837213545777846",
            "img":"https://img.sobot.com/console/common/face/user.png",
            "nick":"招商王",
            "source":"10",
            "enterprise_name":"",
            "user_tels":"13545777846",
            "user_emails":"13545777846@foxmail.com",
            "user_name":"孙盼",
            "province_name":"山东",
            "city_name":"",
            "area_name":"",
            "remark":"意向用户可跟",
            "visitorids":"",
            "service_no":"1011",
            "serviceid":"ea6f8d1a5e8846fd8dfce4ab7057c45c",
            "cid":"bcfb6853edc446c0a4305692b9daf6c8",
            "result_list":[

            ]
        }
    ]
}

# 3.5在线聊天消息

# 3.5.1content对象

参数 类型 必填 名称 备注
companyid String 公司ID 适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
cid String 会话ID
format_time String 时间 格式:yyyy-MM-dd HH:mm:ss
timems String 时间戳 unixtime ms,例如:1539153409792
senderid String 发送人ID 为访客ID或客服ID或机器人ID
sender_name String 发送人
receiverid String 接收人ID 为访客ID或客服ID或机器人ID
receiver_name String 接收人
msg String 聊天内容
docid string 问题id 知识库问题的id 只有sender_type=1的消息有
doc_name string 词条名称 知识库问题的词条名称 只有sender_type=1的消息有
sender_type String 发送方类型 0-访客,1-机器人,2-人工客服
receiver_type String 接收方类型 0-访客,1-机器人,2-人工客服,3-无接收方(表示该消息为留言转离线消息)
msg_offline String 是否是离线消息 1-是,0-否

注: 唯一主键cid+ timems +senderid,机器人和人工可分别评价。

# 3.5.2 请求参数

参数 类型 必填 名称 备注
sys_code String 产品编码 21
type String 消息类型 msg
content List 消息内容

# 3.5.3 请求报文样例

{
    "sys_code":"21",
    "type":"msg",
    "content":[
        {
            "companyid":"5cc2c708202sasad2f72d4bcac362a55",
            "cid":"44c603626e2e4c82a5a49619a8aaa397",
            "format_time":"2017-11-01 12:24:04",
            "timems":"1509510244000",
            "senderid":"33c603626e434c82a5a49619aadde451",
            "sender_name":"冯建武",
            "receiverid":"25e603626e434c82a5a49619aaqw345",
            "receiver_name":"胡丽静",
            "msg":"到还款日,延期3天怎么算",
            "docid":"88c5342f51134db58ea59f430ad16939",
            "doc_name":"来张图片",
            "sender_type":"0",
            "receiver_type":"2",
            "msg_offline":"0"
        }
    ]
}

# 3.6在线服务总结

# 3.6.1content 对象

参数 类型 必填 名称 备注
companyid String 企业ID 适用一个公司多个超管帐号或者多个分公司需要分别统计的情况
cid String 会话ID
visitorid String 访客ID
operationid String 业务单元ID
operation_name String 业务单元名称
req_type String 业务类型ID列表 以-隔开
req_type_name String 业务类型名称列表 以-隔开
summary_status String 处理状态 1-已解决,0-未解决,-1-未勾选
summary_description String 备注
update_time String 更新时间 例如:"1577785628084"
update_staffId String 更新人ID
invalid_flag String 服务总结状态 1 无效会话,0 有效会话
update_staff_name String 编辑服务总结内容客服名称
groupid String 技能组ID
group_name String 技能组名称
fieldid List&lt;String&gt; 自定义字段id列表
field_name List&lt;String&gt; 自定义字段名称
field_value List&lt;String&gt; 自定义字段值
start_time String 会话建立时间

# 3.6.2 请求参数

参数 类型 必填 名称 备注
sys_code String 产品编码 21
type String 消息类型 summary
content List 消息内容

# 3.6.3 请求报文样例

{
    "sys_code":"21",
    "type":"summary",
    "content":[
        {
            "chat_start_time":"1577779079941",
            "group_name":"test",
            "groupid":"ab900e0cea3f4247981631a7bdb0c694",
            "summary_status":"1",
            "field_name":[
                "字段1",
                "字段2"
            ],
            "operation_name":"",
            "update_staff_name":"毛怪",
            "companyid":"7f72b9c5dee8425fba152a216e528cd4",
            "update_time":"1577779099437",
            "invalid_flag":"0",
            "operationid":"1577330071201",
            "field_value":[
                "qweqeqw",
                "eqweqwe"
            ],
            "req_type_name":"手机-电脑",
            "req_type":"1577330173970-1577330182339",
            "update_staffId":"132dd5ef52b44dc3931f181980c61276",
            "cid":"dfdc8f4dfaab44bbb463a5f8960a4cc7",
            "visitorid":"d7a05991e58c35f1dede477a04205f92",
            "summary_description":"qeqe",
            "fieldid":[
                "3fc247578a294a3297a7418d521974fd",
                "39303cc831c641ad93a5f0757cce69d7"
            ]
        }
    ]
}

# 3.7消息转发加密

基于在线用户消息和在线访客消息接口,智齿提供加密功能。

# 3.7.1 加密条件

需要联系智齿对应支撑人员,在智齿统一的业务支撑管理系统中开启加密设置项(先提供消息接收地址),并获取智齿提供的“密钥”进行解密操作,开启设置项后当晚12:00之后开始进行消息主动推送

# 3.7.2 加密方式

采用 AES/CBC/ZeroPadding加密

# 3.7.3 加密范围

开启加密设置项后,加密范围目前为:在线用户消息、在线访客消息接口;type类型为:user及userinfo;加密内容为content字段。

# 3.7.4 加密示例

{
    "type":"user",
    "sys_code":"21",
    "content": " 0PKeYX9heDTiqE8Bi+sFBO9Id1OUvJCw9Okk0j9D/qhKvUyH2wbb61ggyCpO4czYzFvi0S0rrGuMTyYzr5mfwdcnq3nbG8QaZSzHDa3KbFcfF4QGPKU8NU5BvIv6EyU3Ul6KeZ3+ITG6jCD8MxqGE/WcIF1+t213iS1kEyz32TCLXsrrVpFRwz5oMRosaqjuLaofXCKSVSJbo3+/a+I7RQXDM+BYaLAyKn6dyYMTfbEnLCQCx+unkr2KPy2bnr03vGLdYPvNjusXuqitJb1YgToSqw/BfMOtwEjSrjlImtIGpnDtk7yrqxdbf4vF8Q5pPCuMJ65o8z6lwmceznXi/ZHpmDOc4LhSxNF5w5yUlCyjAGFgqe9VzpjsBjHhbNIAKZlMXMI6c5Z3S4p0nDKLfBXZum3PK7A1miyFpqlGbO6MURpU2HF8G3ZJL2woDaWbSrmFMNxjLH8h8KOZTOcYgr9/ptbeHjrA3bIsVDRa8hQ="
}

# 4、错误编码

# 4.1、操作成功

业务操作成功。

错误编码 错误说明
000000 操作成功(除此编码以外的编码为错误编码)

# 4.2、系统异常

系统服务异常。

错误编码 错误说明
900001 token为空
900002 token已失效,请重新获取
900003 signature错误
900004 没有找到公司的api配置信息
999999 系统未知异常

# 4.3、业务异常

业务异常。

错误编码 错误说明
200001 partnerid未传入
200002 公司信息不存在
200003 访客信息不存在
200004 参数不能为空
200005 词条id或词条名称未传入
200006 访客已离线,无法评价
200007 该消息已被评价,无法评价
200008 消息内容未传入
200009 评价类型未传入
200010 评价结果未传入
200011 会话id未传入
200012 消息id未传入
200013 评价状态未传入
200014 机器人信息未传入
210001 该邮箱未注册
210002 邮箱不能为空