自定义IM来源消息

请求和验证方式

消息接口:https://webapi.kf5.com/kchat/message
上传文件接口:https://webapi.kf5.com/kchat/upload

请求和响应格式:Content-Type: application/json; charset=utf-8
将平台域名添加到 Headers:KF5-Domain: {yourdomain}.kf5.com

验证方式,采用 OAuth1.0
最终用于生成签名的 KEY 为:APP KEY + "&"
参与签名的参数:
oauth_consumer_key // APPID
oauth_signature_method // 目前仅支持:HMAC-SHA1
oauth_timestamp // 秒级别时间戳
oauth_nonce // 随机字符串
oauth_version // 目前仅支持:1.0

查看代码示例

拉取客服和客服组信息

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action": "get_agent_states",
    "data": {
        "agent_ids": [122, 586]
    }
}

备注:
参数 data 可以省略,表示查询所有客服的状态和信息

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功",
	"data": {
		"agents":[
			{
				"id":122,
				"name":"客服小叶",
				"display_name":"客服小叶",
				"photo":"https://fs.kf5.com/upload/59/201503/1427102374_568.jpg",
				"max_serve":8,
				"web_status":"online",
				"app_status":"offline"
			},
			{
				"id":586,
				"name":"张伟",
				"display_name":"客服小张",
				"photo":"https://fs.kf5.com/upload/59/201606/57517f60ddb57_352.jpg",
				"max_serve":-1,
				"web_status":"busy",
				"app_status":"online"
			}
		],
		"groups":[
			{
				"id":"13768",
				"name":"售前客服组",
				"agents":[
					"122",
					"586",
					"8358000"
				]
			},
			{
				"id":"22426",
				"name":"支持服务组",
				"agents":[
					"122",
					"5977866"
				]
			}
		]
	}
}

用户创建对话

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"create_chat",
	"chat":{
 		"agent_ids": [122, 586],		// 指定客服
 		"group_ids": [173, 3918],		// 指定客服组
 		"force": 0			// 是否强制分配,可选值:0(溢出分配)、1(强制分配)
	},
	"user":{
		"name":"小刘",
		"openid":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"metadata":[
			{
				"name":"联系地址",
				"value":"四川省成都市锦江区东大街时代1号"
			},
			{
				"name":"正在查看商品",
				"value":"智能手机 http://www.yourdomain.com/goods/123.html"
			}
		]
	}
}

备注:
user.openid:string|integer,用户在客户自己系统或第三方系统中的用户ID;
chat.agent_ids:array,指定受理客服;
chat.group_ids:array,指定受理客服组;
chat.force:integer,可选值 0(溢出分配)、1(强制分配),当设置为 1 时,如果在指定的受理客服[组]范围内没有空闲的客服,则会分配失败;
优先使用 agent_ids 参数,当 group_ids 指定多个客服组时,会按顺序往后溢出分配;

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

用户向客服发送文本消息

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"chat",
	"message":{
		"id":"1",
		"type":"text",
		"to_user":"6452832",		// 客服的用户 id
		"from_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",		// 用户的 openid
		"content":"你好,有个问题需要咨询一下",
		"create_time":1480433249
	}
}

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

上传附件

外部来源发消息至逸创云客服 Kchat IM,目前支持图片、语音、文档、压缩包文件, 文件扩展名:jpg, png, jpeg, bmp, gif, amr, mp3, rar, zip, txt, doc, docx, xls, xlsx, pdf, csv, ppt, pptx, wav, msg, tif, tiff, xlsm,请求时在请求头中添加文件的 MIME Type,例如:Content-Type: image/jpeg。或者是增加 GET 参数 filename 来传递文件名,例如:https://webapi.kf5.com/kchat/upload?filename=%e5%9b%be%e7%89%87.jpg,注意请将 filename 进行 urlencode,并在生成签名字符串时包含该参数

POST https://webapi.kf5.com/kchat/upload

请求参数:

在 Body 中上传文件内容(单次请求只支持上传一个文件)

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功",
	"data": {
		"token": "e84a35c55c4497c0a6622cf2d3b3495b",
		"url": "https://kchat-files-aliyun.kf5.com/d38456182bec44166adb7d9948b1e95a.jpg"
	}
}

用户向客服发送附件消息

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"chat",
	"message":{
		"id":"1",
		"type":"image",     // 支持类型:image、voice、file
		"to_user":"6452832",
		"from_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"token":"e84a35c55c4497c0a6622cf2d3b3495b",		// 上传附件接口返回的 token
		"filename":"商品图片01.jpg",
		"create_time":1480433249
	}
}

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

更新用户信息

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"update_visitor",
	"user":{
		"name":"小刘",
		"openid":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"metadata":[
			{
				"name":"联系地址",
				"value":"四川省成都市锦江区东大街时代1号"
			},
			{
				"name":"正在查看商品",
				"value":"智能手机 http://www.yourdomain.com/goods/123.html"
			}
		]
	}
}

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

用户主动结束对话

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"close_chat",
	"user":{
		"openid":"e4d8c2abfc783e0b8f0d7b4eb93812e5"
	}
}

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

用户主动取消对话排队

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"cancel_queue",
	"user":{
		"openid":"e4d8c2abfc783e0b8f0d7b4eb93812e5"
	}
}

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

用户提交对话满意度评价

请根据 客服邀请用户进行满意度评价的通知 中指定的满意度评价等级进行评价

POST https://webapi.kf5.com/kchat/message

请求参数:

{
	"action":"rating",
	"message":{
		"type":"rating",
        "chat_id":156392,
		"from_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
        "value": 5,
        "reason": "解决了我的问题,谢谢",
		"create_time":1480433249
	}
}

备注:
message.type:消息类型为满意度评价,固定值 rating;
message.chat_id:对话 ID,可以从 客服邀请用户进行满意度评价的通知 中获取到;
message.from_user:用户在客户自己系统或第三方系统中的用户ID,即 openid;
message.value:满意度评分,分数越高越满意,可选值:1 ~ 5;
message.reason:满意度评价内容,可选

接口响应示例:

{
	"error_code": 0,
	"message": "请求成功"
}

接收客服发给用户的文本消息

注意:逸创云客服会将客服发送的消息以 POST 请求异步推送到您后台配置的回调地址,后台配置位置:设置 > 客服接入渠道 > 自定义 IM 来源 > 编辑自定义 IM 来源 > 接收消息的回调地址,这里假设您配置的回调地址是:https://im.yourdomain.com/messages(下同)

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"chat",
	"message":{
		"id":1636228,		// 消息 id
		"appid":1000001,
		"type":"text",
		"chat_id":354345,		// 对话 id
		"from_user":242392,		// 客服 id
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"content":"您好,有什么需要帮助您的吗?",
		"create_time":1480592669
	}
}

用户服务器响应:

状态码 200

接收客服发给用户的图片消息

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"chat",
	"message":{
		"id":1636240,
		"appid":1000001,
		"type":"image",
		"chat_id":354345,
		"from_user":242392,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"filename":"image01.jpg",
		"url":"https://kchat-files-aliyun.kf5.com/d38456182bec44166adb7d9948b1e95a.jpg",
		"create_time":1480594319
	}
}

用户服务器响应:

状态码 200

接收客服发给用户的文件消息

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"chat",
	"message":{
		"id":1636240,
		"appid":1000001,
		"type":"voice" | "file",
		"chat_id":354345,
		"from_user":242392,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"filename":"文件资料.zip",
		"url":"https://kchat-files-aliyun.kf5.com/d38456182bec44166adb7d9948b1e95a.zip",
		"create_time":1480594319
	}
}

用户服务器响应:

状态码 200

接收客服发给用户的视频会议消息

POST https://im.yourdomain.com/messages

请求参数:

{
	"action": "chat",
	"message": {
		"id": 1636240,
		"appid": 1000001,
		"type": "custom",
		"chat_id": 354345,
		"from_user": 242392,
		"to_user": "e4d8c2abfc783e0b8f0d7b4eb93812e5",
        "custom_data": {
            "type": "video",
            "video_url": "https://zhumu.me/j/xxxx"
        },
		"create_time": 1480594319
	}
}

用户服务器响应:

状态码 200

接收对话进入队列的通知

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"into_chat_queue",
	"message":{
		"type":"notice",
		"appid":1000001,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"queue_index":3,		// 对话所在队列的位置
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 200

接收对话进队列位置更新的通知

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"chat_queue_index",
	"message":{
		"type":"notice",
		"appid":1000001,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"queue_index":3,
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 200

接收对话接入成功的通知

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"create_chat_success",
	"message":{
		"type":"notice",
		"appid":1000001,
		"chat_id":354345,
		"from_user":242392,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 200

接收对话创建失败的通知

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"create_chat_failed",
	"message":{
		"type":"notice",
		"appid":1000001,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"reason":"offline" | "busy",		// 对话创建失败的原因,客服离线或忙碌
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 200

接收对话被关闭的通知

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"close_chat",
	"message":{
		"type":"notice",
		"appid":1000001,
		"chat_id":156392,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 200

接收客服邀请用户进行满意度评价的通知

用户提交满意度评价有两种方式,一是通过引导用户访问 message.url 自主完成满意度评价,二是通过 接口 提交满意度评价

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"invite_rating",
	"message":{
		"type":"notice",
		"appid":1000001,
		"chat_id":156392,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"url":"https://yourdomain.kf5.com/customim/rating....",
		"create_time":1480595333
	},
    "rating_setting":{
        "level": 3,
        "items": [
            {"value":5, "label":"满意"},
            {"value":3, "label":"一般"},
            {"value":1, "label":"不满意"}
        ]
    }
}

备注:
message.chat_id:对话 ID;
message.url:进行满意度评价的 WEB 页面,用户在该页面自主完成满意度评价;
rating_setting.level:满意度评价等级,枚举值:2、3、5,管理员可以在后台设置评价等级:设置 >> IM对话设置 >> 满意度评价等级;
rating_setting.items:满意度评价的可用选项列表;
rating_setting.items[i].value:满意度评分,分数越高越满意,可选值:1 ~ 5;
rating_setting.items[i].label:满意度评分对应的满意程度名称。

用户服务器响应:

状态码 200

接收客服主动打开对话的通知

POST https://im.yourdomain.com/messages

请求参数:

{
	"action":"invite_chat",
	"message":{
		"type":"notice",
		"appid":1000001,
		"from_user":242392,
		"to_user":"e4d8c2abfc783e0b8f0d7b4eb93812e5",
		"chat_id":156392,
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 200

错误码说明

错误码说明
40301参数错误
40302签名错误
40401APPID不存在
40303APP已停用
40403ACTION不存在
40305平台已过期
50003创建用户失败
40404未知的消息类型
50201不支持的文件类型
50202文件大小超过限制,具体参见:http://www.kf5.com/product/compare/
50203文件上传失败
40405平台不存在
40001对话已关闭
40002用户不存在
40003对话不存在
40004正在对话中,不能重复创建对话
40005客服不在线
40006客服忙碌
40007请用参数 filename 指定文件名
40008更新用户信息失败
40601不在服务时间
40009用户已被封禁