自定义IM消息来源 V2

简介

自定义IM来源渠道功能让有开发能力的企业开发并接入多个IM消息来源,接入后,让客服统一在逸创云客服上接待各个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

参数签名的参数:

oauth_consumer_key // APPID

oauth_signature_method // 目前仅支持:HMAC-SHA1

oauth_timestamp // 秒级别时间戳

oauth_nonce // 随机字符串

oauth_version // 目前仅支持:1.0

PHP代码示例:

// 请求的接口URL
$url = 'https://webapi.kf5.com/kchat/message';

// 请求方式
$method = 'POST';

// 自定义IM来源的ID和KEY,在工单系统后台设置页面获取
$appid = '1000001';
$appkey = 'a86e77be8e51858b3599ba71ba8d6087';

// 秒级别时间戳
$timestamp = '1480591219';

// 随机字符串,相同时间戳时,nonce应该保持唯一
$nonce = 'dkj94203u';

// 所有需要参与签名的参数
$params = array(
	'oauth_version' => '1.0',
	'oauth_signature_method' => 'HMAC-SHA1',
	'oauth_timestamp' => $timestamp,
	'oauth_nonce' => $nonce,
	'oauth_consumer_key' => $appid
);

// 对参数按键名升序排列
ksort($params, SORT_STRING);

// 将参数连接成字符串
$params_arr = array();
foreach($params as $key => $value){
	$params_arr[] = $key.'='.$value;
}
$params_str = implode('&', $params_arr);

// 用于生成签名的字符串
$sign_str = $method.'&'.urlencode($url).'&'.urlencode($params_str);

// 用于生成签名的KEY
$key = urlencode($appkey).'&';

// 生成签名字符串(先进行HMAC-SHA1加密,再进行Base64加密,再进行urlencode编码)
$signature = urlencode(base64_encode(hash_hmac('sha1', $sign_str, $key, true)));

// 拼接成添加到请求头中的Authorization
$authorization = sprintf('Authorization: OAuth oauth_consumer_key="%s",oauth_signature_method="HMAC-SHA1",oauth_timestamp="%s",oauth_nonce="%s",oauth_version="1.0",oauth_signature="%s"', $appid, $timestamp, $nonce, $signature);

// 结果:
// Authorization: OAuth oauth_consumer_key="1000001",oauth_signature_method="HMAC-SHA1",oauth_timestamp="1480591219",oauth_nonce="dkj94203u",oauth_version="1.0",oauth_signature="Zc5+ptWxqpY%2FzvoGIM+8kw282cA%3D"

拉取客服和客服组信息

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

请求参数:

{
	"action": "get_agent_states"
}

接口响应示例:

{
	"success": true,
	"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 指定多个客服组时,会按顺序往后溢出分配;

接口响应示例:

{
	"success": true,
	"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
	}
}

接口响应示例:

{
	"success": true,
	"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 中上传文件内容(单次请求只支持上传一个文件)

接口响应示例:

{
	"success": true,
	"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
	}
}

接口响应示例:

{
	"success": true,
	"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"
			}
		]
	}
}

接口响应示例:

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

用户主动结束对话

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

请求参数:

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

接口响应示例:

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

用户主动取消对话排队

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

请求参数:

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

接口响应示例:

{
	"success": true,
	"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

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

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....",		// 这是一个 WEB 页面,用户可以在该页面自主完成满意度评价
		"create_time":1480595333
	}
}

用户服务器响应:

状态码 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/pricing
50203文件上传失败
40405平台不存在
40001对话已关闭
40002用户不存在
40003对话不存在
40004正在对话中,不能重复创建对话
40005客服不在线
40006客服忙碌
40007请用参数 filename 指定文件名
40008更新用户信息失败
40601不在服务时间