kf

package
v2.0.9 Latest Latest
Warning

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

 Go to latest Published: Sep 13, 2021 License: Apache-2.0 Imports: 12 Imported by: 2

README

微信客服SDK

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

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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) 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 获取消息

func (*Client) SendMsgOnEvent added in v2.0.9 

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

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

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 util.CommonError, 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 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参数"
	// SDKInvalidCorpID 错误码：40013
	SDKInvalidCorpID Error = "无效的 CorpID"
	// SDKAccessTokenInvalid 错误码：40014
	SDKAccessTokenInvalid Error = "AccessToken 无效"
	// SDKValidateSignatureFailed 错误码：40015
	SDKValidateSignatureFailed Error = "校验签名错误"
	// SDKDecryptMSGFailed 错误码：40016
	SDKDecryptMSGFailed 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 NewSDKErr 

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

NewSDKErr 初始化SDK实例错误信息

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 added in v2.0.9 

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 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.