kf

package
v2.1.5557 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2023 License: Apache-2.0 Imports: 12 Imported by: 0

README

微信客服SDK

相关文档正在梳理中...

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewSDKErr 

func NewSDKErr(code int64, msgList ...string) error

NewSDKErr 初始化SDK实例错误信息

Types

type AccountAddOptions 

type AccountAddOptions struct {
	Name    string `json:"name"`     // 客服帐号名称, 不多于16个字符
	MediaID string `json:"media_id"` // 客服头像临时素材。可以调用上传临时素材接口获取, 不多于128个字节
}

AccountAddOptions 添加客服账号请求参数

type AccountAddSchema 

type AccountAddSchema struct {
	util.CommonError
	OpenKFID string `json:"open_kfid"` // 新创建的客服张号ID
}

AccountAddSchema 添加客服账号响应内容

type AccountDelOptions 

type AccountDelOptions struct {
	OpenKFID string `json:"open_kfid"` // 客服帐号ID, 不多于64字节
}

AccountDelOptions 删除客服账号请求参数

type AccountInfoSchema 

type AccountInfoSchema struct {
	OpenKFID string `json:"open_kfid"` // 客服帐号ID
	Name     string `json:"name"`      // 客服帐号名称
	Avatar   string `json:"avatar"`    // 客服头像URL
}

AccountInfoSchema 客服详情

type AccountListSchema 

type AccountListSchema struct {
	util.CommonError
	AccountList []AccountInfoSchema `json:"account_list"` // 客服账号列表
}

AccountListSchema 获取客服账号列表响应内容

type AccountUpdateOptions 

type AccountUpdateOptions struct {
	OpenKFID string `json:"open_kfid"` // 客服帐号ID, 不多于64字节
	Name     string `json:"name"`      // 客服帐号名称, 不多于16个字符
	MediaID  string `json:"media_id"`  // 客服头像临时素材。可以调用上传临时素材接口获取, 不多于128个字节
}

AccountUpdateOptions 修改客服账号请求参数

type AddContactWayOptions 

type AddContactWayOptions struct {
	OpenKFID string `json:"open_kfid"` // 客服帐号ID, 不多于64字节
	Scene    string `json:"scene"`     // 场景值，字符串类型，由开发者自定义, 不多于32字节, 字符串取值范围(正则表达式)：[0-9a-zA-Z_-]*
}

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 AddContactWaySchema 

type AddContactWaySchema struct {
	util.CommonError
	URL string `json:"url"` // 客服链接，开发者可将该链接嵌入到H5页面中，用户点击链接即可向对应的微信客服帐号发起咨询。开发者也可根据该url自行生成需要的二维码图片
}

AddContactWaySchema 获取客服账号链接响应内容

type CallbackMessage 

type CallbackMessage struct {
	ToUserName string `json:"to_user_name"` // 微信客服组件ID
	CreateTime int    `json:"create_time"`  // 消息创建时间，unix时间戳
	MsgType    string `json:"msgtype"`      // 消息的类型，此时固定为 event
	Event      string `json:"event"`        // 事件的类型，此时固定为 kf_msg_or_event
	Token      string `json:"token"`        // 调用拉取消息接口时，需要传此token，用于校验请求的合法性
}

CallbackMessage 微信客服回调消息

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client 微信客服实例

func NewClient 

func NewClient(cfg *config.Config) (client *Client, err error)

NewClient 初始化微信客服实例

func (*Client) AccountAdd 

func (r *Client) AccountAdd(options AccountAddOptions) (info AccountAddSchema, err error)

AccountAdd 添加客服账号

func (*Client) AccountDel 

func (r *Client) AccountDel(options AccountDelOptions) (info util.CommonError, err error)

AccountDel 删除客服账号

func (*Client) AccountList 

func (r *Client) AccountList() (info AccountListSchema, err error)

AccountList 获取客服账号列表

func (*Client) AccountUpdate 

func (r *Client) AccountUpdate(options AccountUpdateOptions) (info util.CommonError, err error)

AccountUpdate 修复客服账号

func (*Client) AddContactWay 

func (r *Client) AddContactWay(options AddContactWayOptions) (info AddContactWaySchema, err error)

AddContactWay 获取客服账号链接

func (*Client) CustomerBatchGet 

func (r *Client) CustomerBatchGet(options CustomerBatchGetOptions) (info CustomerBatchGetSchema, err error)

CustomerBatchGet 客户基本信息获取

func (*Client) GetCallbackMessage 

func (r *Client) GetCallbackMessage(encryptedMsg []byte) (msg CallbackMessage, err error)

GetCallbackMessage 获取回调事件中的消息内容 

 //Gin框架的使用示例
	r.POST("/v1/event/callback", func(c *gin.Context) {
		var (
			message kf.CallbackMessage
			body []byte
		)
		// 读取原始消息内容
		body, err = c.GetRawData()
		if err != nil {
			c.String(http.StatusInternalServerError, err.Error())
			return
		}
		// 解析原始数据
		message, err = kfClient.GetCallbackMessage(body)
		if err != nil {
			c.String(http.StatusInternalServerError, "消息获取失败")
			return
		}
		fmt.Println(message)
		c.String(200, "ok")
	})

func (*Client) GetCorpQualification 

func (r *Client) GetCorpQualification() (info CorpQualificationSchema, err error)

GetCorpQualification 获取视频号绑定状态 微信客服可接待的客户数，和企业是否已完成主体验证、是否绑定视频号相关。

企业未完成主体验证时，微信客服仅可累计接待100位客户 企业已验证但未绑定视频号时，微信客服仅可累计接待10000位客户 企业已验证且已绑定视频号时，微信客服可接待的客户数不受限制

开发者可获取状态后，在应用等地方提示企业去完成主体验证或绑定视频号。

func (*Client) ReceptionistAdd 

func (r *Client) ReceptionistAdd(options ReceptionistOptions) (info ReceptionistSchema, err error)

ReceptionistAdd 添加接待人员

func (*Client) ReceptionistDel 

func (r *Client) ReceptionistDel(options ReceptionistOptions) (info ReceptionistSchema, err error)

ReceptionistDel 删除接待人员

func (*Client) ReceptionistList 

func (r *Client) ReceptionistList(kfID string) (info ReceptionistListSchema, err error)

ReceptionistList 获取接待人员列表

func (*Client) SendMsg 

func (r *Client) SendMsg(options interface{}) (info SendMsgSchema, err error)

SendMsg 发送消息 当微信客户处于“新接入待处理”或“由智能助手接待”状态下，可调用该接口给用户发送消息。 注意仅当微信客户在主动发送消息给客服后的48小时内，企业可发送消息给客户，最多可发送5条消息；若用户继续发送消息，企业可再次下发消息。 支持发送消息类型：文本、图片、语音、视频、文件、图文、小程序、菜单消息、地理位置。 目前该接口允许下发消息条数和下发时限如下：

用户动作 允许下发条数限制 下发时限 用户发送消息 5条 48 小时

func (*Client) SendMsgOnEvent 

func (r *Client) SendMsgOnEvent(options interface{}) (info SendMsgOnEventSchema, err error)

SendMsgOnEvent 发送事件响应消息 当特定的事件回调消息包含code字段，或通过接口变更到特定的会话状态，会返回code字段。 开发者可以此code为凭证，调用该接口给用户发送相应事件场景下的消息，如客服欢迎语、客服提示语和会话结束语等。 除”用户进入会话事件”以外，响应消息仅支持会话处于获取该code的会话状态时发送，如将会话转入待接入池时获得的code仅能在会话状态为”待接入池排队中“时发送。

目前支持的事件场景和相关约束如下：

事件场景 允许下发条数 code有效期 支持的消息类型 获取code途径 用户进入会话，用于发送客服欢迎语 1条 20秒 文本、菜单 事件回调 进入接待池，用于发送排队提示语等 1条 48小时 文本 转接会话接口 从接待池接入会话，用于发送非工作时间的提示语或超时未回复的提示语等 1条 48小时 文本 事件回调、转接会话接口 结束会话，用于发送结束会话提示语或满意度评价等 1条 20秒 文本、菜单 事件回调、转接会话接口

「进入会话事件」响应消息： 如果满足通过API下发欢迎语条件（条件为：1. 企业没有在管理端配置了原生欢迎语；2. 用户在过去48小时里未收过欢迎语，且未向该用户发过消息），则用户进入会话事件会额外返回一个welcome_code，开发者以此为凭据调用接口（填到该接口code参数），即可向客户发送客服欢迎语。

func (*Client) ServiceStateGet 

func (r *Client) ServiceStateGet(options ServiceStateGetOptions) (info ServiceStateGetSchema, err error)

ServiceStateGet 获取会话状态 0 未处理 新会话接入（客户发信咨询）。可选择：1.直接用API自动回复消息。2.放进待接入池等待接待人员接待。3.指定接待人员（接待人员须处于“正在接待”中，下同）进行接待 1 由智能助手接待 可使用API回复消息。可选择转入待接入池或者指定接待人员处理 2 待接入池排队中 在待接入池中排队等待接待人员接入。可选择转为指定人员接待 3 由人工接待 人工接待中。可选择转接给其他接待人员处理或者结束会话 4 已结束 会话已经结束或未开始。不允许变更会话状态，客户重新发信咨询后会话状态变为“未处理” 注：一个微信用户向一个客服帐号发起咨询后，在48h内，或主动结束会话前（包括接待人员手动结束，或企业通过API结束会话），都算是一次会话

func (*Client) ServiceStateTrans 

func (r *Client) ServiceStateTrans(options ServiceStateTransOptions) (info ServiceStateTransSchema, err error)

ServiceStateTrans 变更会话状态

func (*Client) SyncMsg 

func (r *Client) SyncMsg(options SyncMsgOptions) (info SyncMsgSchema, err error)

SyncMsg 获取消息

func (*Client) UpgradeGroupChatService 

func (r *Client) UpgradeGroupChatService(options UpgradeServiceGroupChatOptions) (info util.CommonError, err error)

UpgradeGroupChatService 为客户升级为客户群服务

func (*Client) UpgradeMemberService 

func (r *Client) UpgradeMemberService(options UpgradeMemberServiceOptions) (info util.CommonError, err error)

UpgradeMemberService 为客户升级为专员服务

func (*Client) UpgradeService 

func (r *Client) UpgradeService(options UpgradeServiceOptions) (info util.CommonError, err error)

UpgradeService 为客户升级为专员或客户群服务

func (*Client) UpgradeServiceCancel 

func (r *Client) UpgradeServiceCancel(options UpgradeServiceCancelOptions) (info util.CommonError, err error)

UpgradeServiceCancel 为客户取消推荐

func (*Client) UpgradeServiceConfig 

func (r *Client) UpgradeServiceConfig() (info UpgradeServiceConfigSchema, err error)

UpgradeServiceConfig 获取配置的专员与客户群

func (*Client) VerifyURL 

func (r *Client) VerifyURL(options SignatureOptions) (string, error)

VerifyURL 验证请求参数是否合法并返回解密后的消息内容 

 //Gin框架的使用示例
	r.GET("/v1/event/callback", func(c *gin.Context) {
		options := kf.SignatureOptions{}
		//获取回调的的校验参数
		if = c.ShouldBindQuery(&options); err != nil {
			c.String(http.StatusUnauthorized, "参数解析失败")
		}
		// 调用VerifyURL方法校验当前请求，如果合法则把解密后的内容作为响应返回给微信服务器
		echo, err := kfClient.VerifyURL(options)
		if err == nil {
			c.String(http.StatusOK, echo)
		} else {
			c.String(http.StatusUnauthorized, "非法请求来源")
		}
	})

type CorpQualificationSchema 

type CorpQualificationSchema struct {
	util.CommonError
	WechatChannelsBinding bool `json:"wechat_channels_binding"` // 	当企业具有绑定成功的视频号时，返回true，否则返回false。 1. 企业申请绑定视频号且由视频号管理员确认后，才为绑定成功状态 2. 至少有一个绑定成功的视频号就会返回true
}

CorpQualificationSchema 获取视频号绑定状态响应内容

type CustomerBatchGetOptions 

type CustomerBatchGetOptions struct {
	ExternalUserIDList []string `json:"external_userid_list"` // external_userid列表
}

CustomerBatchGetOptions 客户基本信息获取请求参数

type CustomerBatchGetSchema 

type CustomerBatchGetSchema struct {
	util.CommonError
	CustomerList          []CustomerSchema `json:"customer_list"`           // 微信客户信息列表
	InvalidExternalUserID []string         `json:"invalid_external_userid"` // 无效的微信客户ID
}

CustomerBatchGetSchema 获取客户基本信息响应内容

type CustomerSchema 

type CustomerSchema struct {
	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
	NickName       string `json:"nickname"`        // 微信昵称
	Avatar         string `json:"avatar"`          // 微信头像。第三方不可获取
	Gender         int    `json:"gender"`          // 性别
	UnionID        string `json:"unionid"`         // unionid，需要绑定微信开发者帐号才能获取到，查看绑定方法: https://open.work.weixin.qq.com/kf/doc/92512/93143/94769#%E5%A6%82%E4%BD%95%E8%8E%B7%E5%8F%96%E5%BE%AE%E4%BF%A1%E5%AE%A2%E6%88%B7%E7%9A%84unionid
}

CustomerSchema 微信客户基本资料

type Error 

type Error string

Error 错误 

const (
	// SDKInitFailed 错误码：50001
	SDKInitFailed Error = "SDK初始化失败"
	// SDKCacheUnavailable 错误码：50002
	SDKCacheUnavailable Error = "缓存无效"
	// SDKUnknownError 错误码：50003
	SDKUnknownError Error = "未知错误"
	// SDKInvalidCredential 错误码：40001
	SDKInvalidCredential Error = "不合法的secret参数"
	// SDKInvalidImageSize 错误码：40009
	SDKInvalidImageSize Error = "无效的图片大小"
	// SDKInvalidCorpID 错误码：40013
	SDKInvalidCorpID Error = "无效的 CorpID"
	// SDKAccessTokenInvalid 错误码：40014
	SDKAccessTokenInvalid Error = "AccessToken 无效"
	// SDKValidateSignatureFailed 错误码：40015
	SDKValidateSignatureFailed Error = "校验签名错误"
	// SDKDecryptMSGFailed 错误码：40016
	SDKDecryptMSGFailed Error = "消息解密失败"
	// SDKMediaIDExceedMinLength 错误码：40058
	SDKMediaIDExceedMinLength Error = "不合法的参数, 请参照具体 API 接口说明进行传参"
	// SDKContentContainsSensitiveInformation 错误码：40201
	SDKContentContainsSensitiveInformation Error = "当前客服账号由于涉及敏感信息，已被封禁，请联系企业微信客服处理"
	// SDKAccessTokenMissing 错误码：41001
	SDKAccessTokenMissing Error = "缺少AccessToken参数"
	// SDKAccessTokenExpired 错误码：42001
	SDKAccessTokenExpired Error = "AccessToken 已过期"
	// SDKApiFreqOutOfLimit 错误码：45009
	SDKApiFreqOutOfLimit Error = "接口请求次数超频"
	// SDKApiForbidden 错误码：48002
	SDKApiForbidden Error = "API 禁止调用"
	// SDKInvalidOpenKFID 错误码：95000
	SDKInvalidOpenKFID Error = "无效的 open_kfid"
	// SDKOpenKFIDNotExist 错误码：95004
	SDKOpenKFIDNotExist Error = "open_kfid 不存在"
	// SDKWeWorkAlready 错误码：95011
	SDKWeWorkAlready Error = "已在企业微信使用微信客服"
	// SDKNotUseInWeCom 错误码：95012
	SDKNotUseInWeCom Error = "未在企业微信使用微信客服"
	// SDKApiNotOpen 错误码：95017
	SDKApiNotOpen Error = "API 功能没有被开启"
)

func (Error) Error 

func (r Error) Error() string

Error 输出错误信息

type ReceptionistListSchema 

type ReceptionistListSchema struct {
	util.CommonError
	ReceptionistList []struct {
		UserID string `json:"userid"` // 接待人员的userid。第三方应用获取到的为密文userid，即open_userid
		Status int    `json:"status"` // 接待人员的接待状态。0:接待中,1:停止接待。第三方应用需具有“管理帐号、分配会话和收发消息”权限才可获取
	} `json:"servicer_list"`
}

ReceptionistListSchema 获取接待人员列表响应内容

type ReceptionistOptions 

type ReceptionistOptions struct {
	OpenKFID   string   `json:"open_kfid"`   // 客服帐号ID
	UserIDList []string `json:"userid_list"` // 接待人员userid列表。第三方应用填密文userid，即open_userid 可填充个数：1 ~ 100。超过100个需分批调用。
}

ReceptionistOptions 添加接待人员请求参数

type ReceptionistSchema 

type ReceptionistSchema struct {
	util.CommonError
	ResultList []struct {
		UserID string `json:"userid"`
		util.CommonError
	} `json:"result_list"`
}

ReceptionistSchema 添加接待人员响应内容

type SendMsgOnEventSchema 

type SendMsgOnEventSchema struct {
	util.CommonError
	MsgID string `json:"msgid"` // 消息ID。如果请求参数指定了msgid，则原样返回，否则系统自动生成并返回。不多于32字节, 字符串取值范围(正则表达式)：[0-9a-zA-Z_-]*
}

SendMsgOnEventSchema 发送事件响应消息

type SendMsgSchema 

type SendMsgSchema struct {
	util.CommonError
	MsgID string `json:"msgid"` // 消息ID。如果请求参数指定了msgid，则原样返回，否则系统自动生成并返回。不多于32字节, 字符串取值范围(正则表达式)：[0-9a-zA-Z_-]*
}

SendMsgSchema 发送消息响应内容

type ServiceStateGetOptions 

type ServiceStateGetOptions struct {
	OpenKFID       string `json:"open_kfid"`       // 客服帐号ID
	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
}

ServiceStateGetOptions 获取会话状态请求参数

type ServiceStateGetSchema 

type ServiceStateGetSchema struct {
	util.CommonError
	ServiceState  int    `json:"service_state"`  // 当前的会话状态，状态定义参考概述中的表格
	ServiceUserID string `json:"service_userid"` // 接待人员的userid，仅当state=3时有效
}

ServiceStateGetSchema 获取会话状态响应内容

type ServiceStateTransOptions 

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时要求必填，接待人员须处于“正在接待”中
}

ServiceStateTransOptions 变更会话状态请求参数

type ServiceStateTransSchema 

type ServiceStateTransSchema struct {
	util.CommonError
	MsgCode string `json:"msg_code"` // 用于发送响应事件消息的code，将会话初次变更为service_state为2和3时，返回回复语code，service_state为4时，返回结束语code。可用该code调用发送事件响应消息接口给客户发送事件响应消息
}

ServiceStateTransSchema 变更会话状态响应内容

type SignatureOptions 

type SignatureOptions struct {
	Signature string `form:"msg_signature"`
	TimeStamp string `form:"timestamp"`
	Nonce     string `form:"nonce"`
	EchoStr   string `form:"echostr"`
}

SignatureOptions 微信服务器验证参数

type SyncMsgOptions 

type SyncMsgOptions struct {
	Cursor string `json:"cursor"` // 上一次调用时返回的next_cursor，第一次拉取可以不填, 不多于64字节
	Token  string `json:"token"`  // 回调事件返回的token字段，10分钟内有效；可不填，如果不填接口有严格的频率限制, 不多于128字节
	Limit  uint   `json:"limit"`  // 期望请求的数据量，默认值和最大值都为1000, 注意：可能会出现返回条数少于limit的情况，需结合返回的has_more字段判断是否继续请求。
}

SyncMsgOptions 获取消息查询参数

type SyncMsgSchema 

type SyncMsgSchema struct {
	ErrCode    int32             `json:"errcode"`     // 返回码
	ErrMsg     string            `json:"errmsg"`      // 错误码描述
	NextCursor string            `json:"next_cursor"` // 下次调用带上该值则从该key值往后拉，用于增量拉取
	HasMore    uint32            `json:"has_more"`    // 是否还有更多数据。0-否；1-是。不能通过判断msg_list是否空来停止拉取，可能会出现has_more为1，而msg_list为空的情况
	MsgList    []syncmsg.Message `json:"msg_list"`    // 消息列表
}

SyncMsgSchema 获取消息查询响应内容

type UpgradeMemberServiceOptions 

type UpgradeMemberServiceOptions struct {
	OpenKFID       string `json:"open_kfid"`       // 客服帐号ID
	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
	Type           int    `json:"type"`            // 表示是升级到专员服务还是客户群服务。1:专员服务
	Member         struct {
		UserID  string `json:"userid"`  // 服务专员的userid
		Wording string `json:"wording"` // 推荐语
	} `json:"member"` // 推荐的服务专员，type等于1时有效
}

UpgradeMemberServiceOptions 为客户升级为专员服务请求参数

type UpgradeServiceCancelOptions 

type UpgradeServiceCancelOptions struct {
	OpenKFID       string `json:"open_kfid"`       // 客服帐号ID
	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
}

UpgradeServiceCancelOptions 为客户取消推荐

type UpgradeServiceConfigSchema 

type UpgradeServiceConfigSchema struct {
	util.CommonError
	MemberRange struct {
		UserIDList       []string `json:"userid_list"`        // 专员userid列表
		DepartmentIDList []string `json:"department_id_list"` // 专员部门列表
	} `json:"member_range"` // 专员服务配置范围
	GroupChatRange struct {
		ChatIDList []string `json:"chat_id_list"` // 客户群列表
	} `json:"groupchat_range"` // 客户群配置范围
}

UpgradeServiceConfigSchema 获取配置的专员与客户群

type UpgradeServiceGroupChatOptions 

type UpgradeServiceGroupChatOptions struct {
	OpenKFID       string `json:"open_kfid"`       // 客服帐号ID
	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
	Type           int    `json:"type"`            // 表示是升级到专员服务还是客户群服务。2:客户群服务
	GroupChat      struct {
		ChatID  string `json:"chat_id"` // 客户群id
		Wording string `json:"wording"` // 推荐语
	} `json:"groupchat"` // 推荐的客户群，type等于2时有效
}

UpgradeServiceGroupChatOptions 为客户升级为客户群服务请求参数

type UpgradeServiceOptions 

type UpgradeServiceOptions struct {
	OpenKFID       string `json:"open_kfid"`       // 客服帐号ID
	ExternalUserID string `json:"external_userid"` // 微信客户的external_userid
	Type           int    `json:"type"`            // 表示是升级到专员服务还是客户群服务。1:专员服务。2:客户群服务
	Member         struct {
		UserID  string `json:"userid"`  // 服务专员的userid
		Wording string `json:"wording"` // 推荐语
	} `json:"member"` // 推荐的服务专员，type等于1时有效
	GroupChat struct {
		ChatID  string `json:"chat_id"` // 客户群id
		Wording string `json:"wording"` // 推荐语
	} `json:"groupchat"` // 推荐的客户群，type等于2时有效
}

UpgradeServiceOptions 为客户升级为专员或客户群服务请求参数

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.