申请客服接待

访客通过开放接口申请机器人或人工客服接待，支持指定客服、客服组、来源页面和访客属性。

请求参数

名称	类型	必填	描述
appKey	string	是	企业 AppKey。
time	int64	是	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数。
checksum	string	是	请求签名，签名规则参考通用说明的数据校验。
checksumAlgorithm	int32	否	签名算法版本，默认 0。

请求体

名称	类型	必填	描述	示例值
uid	string	是	访客外部账号，不能为空，长度不超过 64 个字符	visitor_001
fromPage	string	否	访客发起咨询所在页面 URL	https://example.com/order/10001
fromTitle	string	否	访客来源页面标题或描述	订单详情页
deviceType	string	否	设备描述	Web#Chrome#125.0
fromIp	string	否	访客 IP	220.220.2.1
productId	string	否	产品 ID，如 Android package name 或 iOS bundle id	com.example.app
staffType	int32	否	接待类型。0 表示优先机器人，机器人不可用时转人工；1 表示只申请人工客服	1
robotShuntSwitch	int32	否	访客分流机器人开关。0 表示关闭，1 表示开启	0
robotId	int64	否	指定机器人 ID	30001
staffId	int64	否	指定客服 ID；同时传 staffId 和 groupId 时优先 staffId	10001
groupId	int64	否	指定客服组 ID	20001
bid	string	否	平台电商店铺编号	shop_001
level	int32	否	访客 VIP 等级，取值 0 到 11	3
hotQuestions	int64	否	热门问题配置 ID	-1

返回参数

名称	类型	描述	示例值
code	int32	业务状态码，200 表示成功。	200
message	string	响应信息；成功时可能返回欢迎语纯文本。	success
sessionId	int64	会话 ID。成功接入客服或机器人时返回。	888888
uid	string	访客外部账号。	visitor_001
staffId	int64	客服 ID 或机器人 ID。	10001
staffName	string	客服名称或机器人名称。	张三
staffIcon	string	客服头像地址。	https://example.com/avatar.png
staffType	int32	客服类型。1 表示人工客服，0 表示机器人。	1
rich_text_greet	string	富文本欢迎语；返回该字段时 message 为纯文本内容。	<p>您好</p>
count	int32	排队位置。排队中响应会返回该字段。	3
robotInQueue	int32	是否处于机器人排队流程。1 表示是。	1
transferFrom	int64	转接来源会话 ID。	777777
shop	object	店铺信息。
evaluationModel	object	满意度评价模型，字段以在线系统配置为准。

错误码

状态码	描述
400	请求参数格式错误、缺少必要字段或请求体不是合法 JSON。
401	鉴权失败、签名错误、AppKey 不存在或 time 超出允许范围。
500	服务端处理异常。
8002	业务错误码，HTTP 状态码仍为 200：参数错误，常见于请求体 JSON 不合法、缺少必填字段或字段格式不合法。
8003	业务错误码，HTTP 状态码仍为 200：业务状态错误，例如质检任务状态错误或任务类型不匹配。
14001	业务错误码，HTTP 状态码仍为 200：AppKey 不存在或无效。
14002	业务错误码，HTTP 状态码仍为 200：checksum 签名校验失败。
14003	业务错误码，HTTP 状态码仍为 200：time 与服务器时间相差超过允许范围，或时间参数为空。
14004	业务错误码，HTTP 状态码仍为 200：请求内容错误，例如请求体格式错误、缺少必填字段或字段值不合法。
14005	业务错误码，HTTP 状态码仍为 200：无客服在线。
14006	业务错误码，HTTP 状态码仍为 200：访客正在排队。
14008	业务错误码，HTTP 状态码仍为 200：IP 白名单限制或 IP 被拦截。
14009	业务错误码，HTTP 状态码仍为 200：请求过于频繁。
14010	业务错误码，HTTP 状态码仍为 200：留言功能关闭。
14011	业务错误码，HTTP 状态码仍为 200：接口未开放或被停用。
14014	业务错误码，HTTP 状态码仍为 200：访客处于挂起状态。
14015	业务错误码，HTTP 状态码仍为 200：访客正在分流中。
14500	业务错误码，HTTP 状态码仍为 200：系统内部错误。

postEndpoint

/openapi/event/applyStaff

curl -X POST "https://qiyukf.com/openapi/event/applyStaff?appKey=string&time=0&checksum=string" \  -H "Content-Type: application/json" \  -d '{    "uid": "visitor_001"  }'

{
  "code": 200,
  "message": "success",
  "sessionId": 888888,
  "uid": "visitor_001",
  "staffId": 10001,
  "staffName": "张三",
  "staffIcon": "https://example.com/avatar.png",
  "staffType": 1,
  "rich_text_greet": "<p>您好</p>",
  "count": 3,
  "robotInQueue": 1,
  "transferFrom": 777777,
  "shop": {},
  "evaluationModel": {}
}

空

{
  "code": 8002,
  "message": "参数错误，常见于请求体 JSON 不合法、缺少必填字段或字段格式不合法。"
}

{
  "code": 8003,
  "message": "业务状态错误，例如质检任务状态错误或任务类型不匹配。"
}

{
  "code": 14001,
  "message": "AppKey 不存在或无效。"
}

{
  "code": 14002,
  "message": "checksum 签名校验失败。"
}

{
  "code": 14003,
  "message": "time 与服务器时间相差超过允许范围，或时间参数为空。"
}

{
  "code": 14004,
  "message": "请求内容错误，例如请求体格式错误、缺少必填字段或字段值不合法。"
}

{
  "code": 14005,
  "message": "无客服在线。"
}

{
  "code": 14006,
  "message": "访客正在排队。"
}

{
  "code": 14008,
  "message": "IP 白名单限制或 IP 被拦截。"
}

{
  "code": 14009,
  "message": "请求过于频繁。"
}

{
  "code": 14010,
  "message": "留言功能关闭。"
}

{
  "code": 14011,
  "message": "接口未开放或被停用。"
}

{
  "code": 14014,
  "message": "访客处于挂起状态。"
}

{
  "code": 14015,
  "message": "访客正在分流中。"
}

{
  "code": 14500,
  "message": "系统内部错误。"
}