一、满意度配置查询
接口： POST /openapi/im/satisfaction/query
请求类型： application/json;charset=utf-8
查询当前租户的调查模板、展示文案、选项、触发开关及评价时效。可同时查询指定 API 渠道的满意度开关。
1.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
| channelId | string | 否 | 当前租户的 API 渠道 ID；指定后增加返回渠道满意度开关 |
只查询租户配置时发送 {}。同时查询渠道开关时发送：
{
"channelId": "channel-api-001"
}1.2 响应参数
响应中的 success 表示业务是否成功，code 为字符串业务码，message 为提示文案，data 为配置对象。
| data 字段 | 类型 | 说明 |
| type | string | 模板类型，radioTagText 表示选项式调查 |
| satisfyTitle | string | 邀请文案，可能包含占位符；实际展示使用邀请推送中的文案 |
| satisfyThank | string | 感谢文案，实际展示使用邀请推送中的文案 |
| aging | boolean | 是否限制评价有效期 |
| agingTimeout | integer | 有效期时长，单位小时；aging=false 时不据此限制 |
| systemClosePushCsr | boolean | 是否在系统结束会话时邀请评价 |
| agentClosePushCsr | boolean | 是否在客服结束会话时邀请评价 |
| customerClosePushCsr | boolean | 访客结束会话时的评价展示开关 |
| agentPushCsr | boolean | 是否允许客服主动邀请评价 |
| customerPushCsr | boolean | 访客主动评价展示开关 |
| radioTagText | array | 按配置顺序返回评价选项，包含未启用项 |
| channelSatisfaction | boolean，条件返回 | 指定 channelId 时返回渠道满意度开关，未指定时省略 |
radioTagText 选项字段：
| 字段 | 类型 | 说明 |
| key | string | 选项标识，上报时使用 |
| name | string | 选项展示名称 |
| icon | string | 图标 URL，可为空 |
| reason | array of string | 可选原因标签，支持多选；空数组表示无标签 |
| proposalStatus | string | required：建议必填；unRequired：选填；notShow：不展示 |
| defaultIndex | integer | 默认选项在原始配置数组中的位置，从 1 开始；各选项中该值一致 |
| use | boolean | 是否启用，只有 true 的选项可展示和提交 |
按未过滤的原始数组定位默认选项。默认选项未启用时，由访客选择其他启用项，不自动选择替代项。
1.3 响应示例
{
"success": true,
"code": "200",
"message": "200 ok!",
"data": {
"type": "radioTagText",
"satisfyTitle": "请评价本次服务。",
"satisfyThank": "感谢您的评价。",
"aging": true,
"agingTimeout": 24,
"systemClosePushCsr": true,
"agentClosePushCsr": true,
"customerClosePushCsr": false,
"agentPushCsr": true,
"customerPushCsr": false,
"channelSatisfaction": true,
"radioTagText": [
{
"key": "satisfied",
"name": "满意",
"icon": "https://assets.example.com/satisfaction/satisfied.png",
"reason": ["解答清晰", "处理及时"],
"proposalStatus": "unRequired",
"defaultIndex": 1,
"use": true
},
{
"key": "unsatisfied",
"name": "不满意",
"icon": "https://assets.example.com/satisfaction/unsatisfied.png",
"reason": ["未解决问题", "等待时间长"],
"proposalStatus": "required",
"defaultIndex": 1,
"use": true
}
]
}
}查询说明：
- 查询不会产生邀请或修改配置。配置查询成功、渠道开关开启均不代表可以直接上报某个会话的评价。
- 模板不存在或指定的 API 渠道无效时返回业务错误。
- 渠道未启用、渠道满意度开关关闭或全部选项停用时，仍可查询已配置的信息；无启用选项时不展示可提交调查。
- 两个访客展示开关用于了解租户配置，本版本的结果上报仍要求先收到邀请。
二、满意度结果上报
接口： POST /openapi/im/satisfaction/report
请求类型： application/json;charset=utf-8
提交已收到邀请的 OpenAPI 会话评价。每个会话只允许评价一次。
2.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
| channelId | string | 是 | 邀请推送中的 API 渠道 ID |
| sessionId | string | 是 | 邀请推送中的会话 ID |
| messageId | string | 是 | 邀请推送中的消息 ID，须对应 csrInvite |
| satisfactionData | object | 是 | 评价数据 |
| satisfactionData.satisfactionKey | string | 是 | 选择的启用选项 key |
| satisfactionData.satisfactionReason | array of string | 否 | 所选选项下的原因标签，省略或空数组表示未选择 |
| satisfactionData.satisfactionProposal | string | 条件必填 | 建议文本，按选项的 proposalStatus 判断 |
请求示例：
{
"channelId": "channel-api-001",
"sessionId": "session-001",
"messageId": "invite-message-001",
"satisfactionData": {
"satisfactionKey": "satisfied",
"satisfactionReason": ["解答清晰", "处理及时"],
"satisfactionProposal": "希望继续保持。"
}
}2.2 响应参数
| data 字段 | 类型 | 说明 |
| sessionId | string | 被评价的会话 ID |
| satisfactionData | object | 提交成功的评价结果 |
| satisfactionData.satisfactionType | string | 评价类型，radioTagText |
| satisfactionData.satisfactionKey | string | 选项 key |
| satisfactionData.satisfactionName | string | 平台根据配置返回的选项名称 |
| satisfactionData.satisfactionIcon | string | 平台根据配置返回的选项图标 |
| satisfactionData.satisfactionReason | array of string | 提交的原因标签 |
| satisfactionData.satisfactionProposal | string | 提交的建议文本，无内容时可为空 |
2.3 响应示例
{
"success": true,
"code": "200",
"message": "200 ok!",
"data": {
"sessionId": "session-001",
"satisfactionData": {
"satisfactionType": "radioTagText",
"satisfactionKey": "satisfied",
"satisfactionName": "满意",
"satisfactionIcon": "https://assets.example.com/satisfaction/satisfied.png",
"satisfactionReason": ["解答清晰", "处理及时"],
"satisfactionProposal": "希望继续保持。"
}
}
}2.4 提交规则
- 渠道、会话及邀请消息必须属于同一有效邀请，访客信息由会话确定；不接受其他渠道的会话评价。
- 须开启渠道满意度，配置有效模板及启用选项，访客和人工客服均至少发送过一条消息。
- 每个会话只接受第一次有效评价，之后提交相同或不同结果均返回“已评价”，不会覆盖原结果。
- 原因标签必须来自所选选项，不能重复；选项未配置原因标签时省略或提交空数组。
- proposalStatus=required 时建议去除首尾空白后不能为空；unRequired 时可省略；notShow 时省略或留空。
- aging=true 时评价受配置时长限制，重复邀请按最新有效邀请的起点计算；aging=false 时不受该时长限制。有效性以平台提交校验为准。
- 会话结束后仍可提交有效邀请。客户提交选项 key，评价类型、名称和图标由平台根据配置确定。
- 邀请后配置变化时，提交按当前有效配置校验。收到选项或建议规则错误时重新查询配置并请访客确认，不自动更改访客选择。
只有 success=true 才将调查展示为提交成功。响应超时后重报可能返回“已评价”，该状态不能用于确认已提交的内容与重报内容一致。