消息回调
消息回调
创建应用后，你可以在 环信控制台 开通消息回调和回调异常缓存功能。
消息回调概述
消息回调指事件发生之前或之后，环信 IM 服务器会以 HTTP POST 请求的形式向你的应用服务器发送通知。根据是否干预消息投递，回调分为两类：
- 发送前回调：环信服务器收到用户发送的上行单聊、群组或聊天室消息之后、将该消息下发给目标用户之前，环信服务器会通过 HTTP/HTTPS POST 请求通知给你的应用服务器。应用服务器可以通过发送前回调实时处理用户的聊天消息，例如，拦截包含文本、图片、自定义消息等类型的消息。
- 发送后回调：发送消息或进行群组、聊天室或联系人相关操作后，环信服务器向你的应用服务器发送回调请求。该类回调通常用于 app 后台需要实现必要的数据同步。
开通服务
消息回调
你可以根据当前的套餐包版本开通该服务：
- 免费版/专业版：点击 立即升级 升级至专业版或旗舰版。
- 专业版：点击 单独购买 单独购买该服务。
- 旗舰版：点击 免费开通 开通该服务。
回调异常缓存
对于发送后回调，每条回调请求发送失败仅重试一次，重试失败后即丢弃。若有特殊需求不能丢失回调消息的情况下，可开通回调异常缓存功能。
服务开通后，你可以使用 查询回调异常缓存和 补发回调储存信息 接口。
你可以根据当前的套餐包版本开通该服务：
- 免费版：点击 立即升级 升级至专业版或旗舰版，然后再点击 立即购买 单独付费订阅该服务。
- 专业版/旗舰版：点击 立即购买 单独付费订阅该服务。
配置消息回调规则
你最多可以配置 4 条发送前和发送后回调规则。配置回调规则后，环信服务器会自动为该规则生成 secret，向你的 app server 发送数据时会基于该 secret 生成签名（即请求中的 security 参数），作为你的服务器识别环信服务器的依据。若要使用自定义密钥，可联系环信商务。
发送前回调
在 消息回调 页面，点击 添加回调规则。在弹出的对话框中，点击 发送前回调，配置相关参数。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 规则名称 | 是 | 支持中英文字符，最多可包含 32 个字符。规则名称必须唯一。 |
| 会话类型 | 是 | 会话类型：单聊、群组、聊天室 和 消息编辑。 |
| 消息类型 | 是 | 支持发送前回调的消息类型包括文本、图片、视频、位置、语音、文件、命令消息和自定义消息。 |
| 等待响应时间 | 是 | 后台判断超时时间，默认为 200 毫秒。如果回调超时无应答，消息默认会正常下发，支持修改消息处理逻辑。 |
| 调用失败时默认策略 | 是 | 当你的服务器返回结果异常或等待时间内未返回结果时，消息放行或不放行。 |
| 消息拦截报错时显示 | 是 | 当消息被拦截时，是否通知发送者 SDK 消息发送失败： - 报错：通知发送者 SDK 消息发送失败，发送者会感知到消息发送失败； - 不报错：不通知发送者 SDK 消息发送失败，发送者不会感知消息发送失败。 |
| 启用状态 | 是 | 回调规则是否立即生效： - 启用：立即生效； - 关闭：暂不生效。 建议首次创建配置为 关闭，等你的服务器配置好验证信息后再修改为 启用。 |
| 回调地址 | 是 | 回调 URL，HTTP 和 HTTPS 的回调地址均支持。 |
发送后回调
在 消息回调 页面，点击 添加回调规则。在弹出的对话框中，点击 发送后回调，配置相关参数。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 规则名称 | 是 | 规则名称，只支持字母、数字和下划线，不支持中文字符，且长度不超过 32 字符。规则名称必须唯一。 |
| 回调地址 | 是 | 即时通讯 IM 服务器会将消息推送到指定的 URL 地址，支持针对不同类型的消息配置不同的 HTTP 和 HTTPS 回调地址。 |
| 启用状态 | 是 | 是否启用该规则。 |
| 回调类型 | 是 | 回调类型。你可以选择对各种类型的单聊、群聊、和聊天室消息以及各种事件进行回调，详见 回调事件。 提示 对于表情回复 Reaction 和子区 Thread，如要获取回调事件，无需单独配置，只需选择对应的消息类型即可。例如，如果需要单聊文本消息的 Reaction，你需要选中 单聊消息 > 文本消息，服务器发送回调事件时即会返回 Reaction 信息。 |
| 消息类型 | 是 | 需要回调的类型： - 聊天消息：发送成功的消息，包括通过客户端和 REST API 发送的消息。这些消息与通过 REST 导出的聊天记录查询到的消息一致。例如，用户 u1 向用户 u2 发送消息，则会产生一条聊天消息，与接收方是否在线无关。收到的消息中 from 为 u1，to 为 u2。用户 u1 在群组 g1 中发送消息，则会产生一条聊天消息，收到的消息中 from 为 u1，to 为 g1，且返回值包含 group_id 字段。- 离线消息：消息发送时接收方为离线的消息。例如：单聊中发送消息，若对端用户不在线，则会产生一条离线消息；在群聊中发送消息，若有几个群成员不在线，则会产生几条离线消息，这些离线消息的 to 参数为接收消息用户的 ID，并不是群组 ID。App 可以通过推送服务对这些消息进行个性化推送。 |
| 消息来源 | 是 | 需要回调的消息的来源： - SDK 消息：通过 SDK 发送的消息。 - Rest 消息：通过 REST API 发送的消息。 |
| From ID | 否 | 消息发送方或操作者的用户 ID。每行输入一个用户 ID，一次最多输入 50 条。设置该参数后，环信服务器只针对该用户发送的消息及执行的操作（例如好友、群组或聊天室相关操作）进行回调。若不指定该参数，规则对发送方或操作者不限制。 |
| To ID | 否 | 单聊的消息或事件接收方的用户 ID。每行输入一个用户 ID，一次最多输入 50 条。若不指定该参数，规则对接收方不限制。 |
| 群组/聊天室 ID | 否 | 群组或聊天室 ID。每行输入一个群组 ID 或聊天室 ID，一次最多输入 50 条。设置该参数后，环信服务器只针对该群组中的消息或事件进行回调。若不指定该参数，规则对群组和聊天室不限制。 |
| 扩展字段中的 Key | 否 | 消息扩展字段中的属性 key。每行输入一个 key，一次最多输入 50 条。设置该参数后，只针对包含该属性 Key 的消息进行回调。若不指定该参数，规则对消息扩展字段不限制。 |
其中，From ID、To ID、群组/聊天室 ID 和扩展字段中的 Key 为配置发送后回调规则时需指定的高级筛选条件，配置示例如下：
仅对单聊的回调：仅设置 From ID 和 To ID。指定的发送方向接收方发单聊消息或对该好友进行操作（如删除好友）时收到回调消息。例如，From ID 设置为 test 1，To ID 设置为 test 2，test 1 向 test 2 发单聊消息时收到回调。
仅对群组或聊天室的回调：仅设置群组/聊天室 ID 参数。这种情况下，只有在指定的群组或聊天室中发送消息或进行操作时收到回调。例如，群组/聊天室 ID 设置为群组 ID 228978，则仅在该群组中发送消息时收到回调。
仅对群聊中某个用户的回调：仅设置 From ID 和 群组/聊天室 ID。这种情况下，只有群组或聊天室中的指定用户发送消息或执行操作时收到回调。例如，From ID 设置为 test 1，群组/聊天室 ID 设置为群组 ID 228978，仅 test 1 用户在群组中发送消息时收到回调。
提示
若 From ID、To ID 和 群组/聊天室 ID 同时设置，发送方向接收方发送单聊、群聊消息时不会收到回调。
发送后回调失败告警配置
发送后回调若在一定时间内达到累计失败次数会封禁该 app 的回调规则。为及时了解发送后回调的失败次数，进行相应处理，你可以设置发送后回调告警，避免 app 的回调规则被封禁。
在 消息回调 页面，点击回调规则列表右上方的 回调失败告警。在弹出的对话框中，配置告警参数。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 告警开关 | 是 | 是否开启发送后回调失败告警功能。 |
| 告警策略 | 是 | - 告警间隔：触发告警的时间间隔，单位为 5 分钟。 - 触发次数：告警间隔内触发告警的回调失败次数。 |
| 邮箱地址 | 是 | 接收发送后回调失败告警的邮箱地址。一次最多可输入 20 个，每行一个。 |