polish:客服链接支持自定义参数

Author: NICEXAI

account.go

@@ -109,6 +109,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_-]*

servicestate.go

@@ -31,7 +31,8 @@ type ServiceStateGetSchema struct {
 //1	由智能助手接待	可使用API回复消息。可选择转入待接入池或者指定接待人员处理。
 //2	待接入池排队中	在待接入池中排队等待接待人员接入。可选择转为指定人员接待
 //3	由人工接待	人工接待中。可选择结束会话
-//4	已结束	会话已经结束。不允许变更会话状态，等待用户重新发起咨询
+//4	已结束	会话已经结束或未开始。不允许变更会话状态，等待用户发起咨询
+// 注：一个微信用户向一个客服帐号发起咨询后，在48h内，或主动结束会话前（包括接待人员手动结束，或企业通过API结束会话），都算是一次会话
 func (r *Client) ServiceStateGet(options ServiceStateGetOptions) (info ServiceStateGetSchema, err error) {
 	data, err := util.HttpPost(fmt.Sprintf(serviceStateGetAddr, r.accessToken), options)
 	if err != nil {
@@ -49,7 +50,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 变更会话状态

syncmsg.go

@@ -24,7 +24,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"`		// 消息列表
 }

syncmsg/message.go

@@ -3,8 +3,8 @@ 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-客服回复消息
@@ -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"`									// 事件消息
 }
 

syncmsg/syncmsg.go

@@ -5,10 +5,10 @@ import "encoding/json"
 // Message 同步的消息内容
 type Message 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，该字段不返回）
 	SendTime uint64 `json:"send_time"`					// 消息发送时间
-	Origin uint32 `json:"origin"`						// 消息来源。3-客户回复的消息 4-系统推送的消 息
+	Origin uint32 `json:"origin"`						// 消息来源。3-微信客户发送的消息 4-系统推送的事件消息 5-接待人员在企业微信客户端发送的消息
 	MsgType string `json:"msgtype"`						// 消息类型
 	EventType string `json:"event_type"`				// 事件类型
 	OriginData []byte `json:"origin_data"`				// 原始数据内容