feat:微信客服链接支持自定义参数 (#438)

* 添加微信客服SDK

* polish:优化签名函数

* polish：优化注释内容

* polish:复用已有的Token以及CommonError,移除无用的输出

* polish:复用已有的消息加解密

* fix:修复错误信息被覆盖的问题

* polish:go fmt 文件

* polish:客服链接支持自定义参数并更新注释文档内容

work/kf/account.go

@@ -150,6 +150,10 @@ func (r *Client) AccountList() (info AccountListSchema, err error) {
 }
 
 // AddContactWayOptions 获取客服账号链接
+// 1.若scene非空，返回的客服链接开发者可拼接scene_param=SCENE_PARAM参数使用，用户进入会话事件会将SCENE_PARAM原样返回。其中SCENE_PARAM需要urlencode，且长度不能超过128字节。
+// 如 https://work.weixin.qq.com/kf/kfcbf8f8d07ac7215f?enc_scene=ENCGFSDF567DF&scene_param=a%3D1%26b%3D2
+// 2.历史调用接口返回的客服链接（包含encScene=XXX参数），不支持scene_param参数。
+// 3.返回的客服链接，不能修改或复制参数到其他链接使用。否则进入会话事件参数校验不通过，导致无法回调。
 type AddContactWayOptions struct {
 	OpenKFID string `json:"open_kfid"` // 客服帐号ID, 不多于64字节
 	Scene    string `json:"scene"`     // 场景值，字符串类型，由开发者自定义, 不多于32字节, 字符串取值范围(正则表达式)：[0-9a-zA-Z_-]*

work/kf/servicestate.go

@@ -32,7 +32,8 @@ type ServiceStateGetSchema struct {
 //1	由智能助手接待	可使用API回复消息。可选择转入待接入池或者指定接待人员处理。
 //2	待接入池排队中	在待接入池中排队等待接待人员接入。可选择转为指定人员接待
 //3	由人工接待	人工接待中。可选择结束会话
-//4	已结束	会话已经结束。不允许变更会话状态，等待用户重新发起咨询
+//4	已结束	会话已经结束或未开始。不允许变更会话状态，等待用户发起咨询
+// 注：一个微信用户向一个客服帐号发起咨询后，在48h内，或主动结束会话前（包括接待人员手动结束，或企业通过API结束会话），都算是一次会话
 func (r *Client) ServiceStateGet(options ServiceStateGetOptions) (info ServiceStateGetSchema, err error) {
 	var (
 		accessToken string
@@ -60,7 +61,7 @@ type ServiceStateTransOptions struct {
 	OpenKFID       string `json:"open_kfid"`       // 客服帐号ID
 	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
 	ServiceState   int    `json:"service_state"`   // 变更的目标状态，状态定义和所允许的变更可参考概述中的流程图和表格
-	ServicerUserID string `json:"servicer_userid"` // 接待人员的userid，当state=3时要求必填
+	ServicerUserID string `json:"servicer_userid"` // 接待人员的userid，当state=3时要求必填，接待人员须处于“正在接待”中
 }
 
 // ServiceStateTrans 变更会话状态

work/kf/syncmsg.go

@@ -25,7 +25,7 @@ type SyncMsgOptions struct {
 type syncMsgSchema struct {
 	ErrCode    int32                    `json:"errcode"`     // 返回码
 	ErrMsg     string                   `json:"errmsg"`      // 错误码描述
-	NextCursor string                   `json:"next_cursor"` // 下次调用带上该值则从该key值往后拉，用于增量拉取
+	NextCursor string                   `json:"next_cursor"` // 下次调用带上该值，则从当前的位置继续往后拉，以实现增量拉取。强烈建议对改该字段入库保存，每次请求读取带上，请求结束后更新。避免因意外丢，导致必须从头开始拉取，引起消息延迟。
 	HasMore    uint32                   `json:"has_more"`    // 是否还有更多数据。0-否；1-是。不能通过判断msg_list是否空来停止拉取，可能会出现has_more为1，而msg_list为空的情况
 	MsgList    []map[string]interface{} `json:"msg_list"`    // 消息列表
 }

work/kf/syncmsg/message.go

@@ -3,11 +3,11 @@ package syncmsg
 // BaseMessage 接收消息
 type BaseMessage struct {
 	MsgID              string `json:"msgid"`           // 消息ID
-	OpenKFID           string `json:"open_kfid"`       // 客服帐号ID
-	ExternalUserID     string `json:"external_userid"` // 客户UserID
+	OpenKFID           string `json:"open_kfid"`       // 客服帐号ID（msgtype为event，该字段不返回）
+	ExternalUserID     string `json:"external_userid"` // 客户UserID（msgtype为event，该字段不返回）
 	ReceptionistUserID string `json:"servicer_userid"` // 接待客服userID
 	SendTime           uint64 `json:"send_time"`       // 消息发送时间
-	Origin             uint32 `json:"origin"`          // 消息来源。3-客户回复的消息 4-系统推送的消息 5-客服回复消息
+	Origin             uint32 `json:"origin"`          // 消息来源。3-微信客户发送的消息 4-系统推送的事件消息 5-接待人员在企业微信客户端发送的消息
 }
 
 // Text 文本消息
@@ -119,6 +119,7 @@ type EnterSessionEvent struct {
 		OpenKFID       string `json:"open_kfid"`       // 客服账号ID
 		ExternalUserID string `json:"external_userid"` // 客户UserID
 		Scene          string `json:"scene"`           // 进入会话的场景值，获取客服帐号链接开发者自定义的场景值
+		SceneParam     string `json:"scene_param"`     // 进入会话的自定义参数，获取客服帐号链接返回的url，开发者按规范拼接的scene_param参数
 	} `json:"event"` // 事件消息
 }