消息回调
消息回调
创建应用后，你可以在 环信控制台 开通消息回调和回调异常缓存功能。
消息回调概述
消息回调指事件发生之前或之后，环信 IM 服务器会以 HTTP POST 请求的形式向你的应用服务器发送通知。根据是否干预消息投递，回调分为两类：
- 发送前回调：环信服务器收到用户发送的上行单聊、群组或聊天室消息之后、将该消息下发给目标用户之前，环信服务器会通过 HTTP/HTTPS POST 请求通知给你的应用服务器。应用服务器可以通过发送前回调实时处理用户的聊天消息，例如，拦截包含文本、图片、自定义消息等类型的消息。
- 发送后回调：发送消息或进行群组、聊天室或联系人相关操作后，环信服务器向你的应用服务器发送回调请求。该类回调通常用于 app 后台需要实现必要的数据同步。
开通服务
消息回调
你可以根据当前的套餐包版本开通该服务：
- 免费版：点击 立即升级 升级至专业版或旗舰版。
- 专业版：点击 单独购买 单独购买该服务。
- 旗舰版：点击 免费开通 开通该服务。
回调异常缓存
对于发送后回调，每条回调请求发送失败仅重试一次，重试失败后即丢弃。若有特殊需求不能丢失回调消息的情况下，可开通回调异常缓存功能。
服务开通后，你可以使用 查询异常缓存数据和 补发异常回调数据 接口。
你可以根据当前的套餐包版本开通该服务：
- 免费版：点击 立即升级 升级至专业版或旗舰版，然后再点击 立即购买 单独付费订阅该服务。
- 专业版/旗舰版：点击 立即购买 单独付费订阅该服务。
配置消息回调规则
你最多可以配置 4 条发送前回调和 4 条发送后回调规则。配置回调规则后，环信服务器会自动为该规则生成 secret，向你的 App Server 发送数据时会基于该 secret 生成签名（即请求中的 security 参数），作为你的服务器识别环信服务器的依据。若要使用自定义密钥，可联系环信商务。
提示
如果你已在测试版应用中配置发送前回调或发送后回调地址，应用上线后请及时检查，并按需切换为正式环境地址。
发送前回调
在 消息回调 页面，点击 添加回调规则。在弹出的对话框中，选择 发送前回调，配置相关参数。
基本配置
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 规则名称 | 是 | 支持中英文字符，最多可包含 32 个字符。规则名称必须唯一。 |
| 会话类型 | 是 | 会话类型： - 单聊：单聊会话中发送前的消息。 - 群组：群组会话中发送前的消息。 - 聊天室：聊天室会话中发送前的消息。 - 消息编辑：单聊、群组或聊天室会话中对发送成功的消息进行修改时的消息（发送前）。 |
| 消息类型 | 是 | 支持发送前回调的消息类型包括文本、图片、视频、位置、语音、文件、命令消息和自定义消息。 |
| 等待响应时间 | 是 | 后台判断超时时间，默认为 200 毫秒。如果回调超时无应答，消息默认会正常下发，支持修改消息处理逻辑。 |
| 调用失败时默认策略 | 是 | 当你的服务器返回结果异常或等待时间内未返回结果时，消息放行或不放行。 |
| 消息拦截报错时显示 | 是 | 当消息被拦截时，是否通知发送者 SDK 消息发送失败： - 报错：通知发送者 SDK 消息发送失败，发送者会感知到消息发送失败； - 不报错：不通知发送者 SDK 消息发送失败，发送者不会感知消息发送失败。 |
| 启用状态 | 是 | 回调规则是否立即生效： - 启用：立即生效； - 关闭：暂不生效。 建议首次创建配置为 关闭，等你的服务器配置好验证信息后再修改为 启用。 |
回调路由配置
回调路由用于在同一个 App Key 下，将不同消息按环境维度分别回调至不同的回调地址。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 回调环境 | 是 | 仅支持字母和数字，长度不超过 8 个字符。默认为 default，不可删除。 |
| 回调地址 | 否 | 最大长度不超过 512 个字符。为空时表示该环境不走回调。 |
回调路由的适用范围如下：
| 回调类型 | 生效范围 | 说明 |
|---|---|---|
| 发送前回调 | 仅对 SDK 发送的消息 生效（不支持群组/聊天室的定向消息）。 | 消息下发给目标用户前，你的服务器可判断是否拦截或修改消息内容。 |
| 发送后回调 | 对 SDK 和 REST API 发送的消息 均生效。 | 消息成功发送后，通知你的服务器。 |
回调路由的配置规则说明如下：
- 每个回调阶段最多可配置 8 条路由，包含默认路由
default。 - 发送前回调与发送后回调的 回调路由相互独立，即各自维护自己的环境与地址映射表。
如果发送消息时传入了回调环境参数，回调路由命中逻辑：
- 消息携带环境值且精确匹配当前阶段的有效路由，按该环境值路由。
- 消息携带环境值但未命中有效路由，不触发回调，
default在此场景下不生效。 - 消息未携带环境值，自动路由至
default环境对应的回调地址。 - 若同一消息需同时触发发送前与发送后回调，在两个阶段必须配置 相同的回调环境值，以便消息中只需携带一个环境值即可同时生效。例如，若发送前回调配置
test -> url1，发送后回调配置test -> url2，则消息中只需携带一个回调环境值：test。
发送后回调
在 消息回调 页面，点击 添加回调规则。在弹出的对话框中，选择 发送后回调，配置相关参数。
基本过滤
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 规则名称 | 是 | 仅支持字母、数字和下划线，不支持中文字符，长度不超过 32 字符。规则名称必须唯一。 |
| 启用状态 | 是 | 是否启用该规则。 |
| 回调类型 | 是 | 你可选择对单聊、群聊、聊天室消息以及各类事件进行回调，详见 回调事件。 提示 对于表情回复 Reaction 和子区 Thread，无需单独配置，只需选择对应的消息类型即可。例如，若需回调单聊文本消息的 Reaction，选中 单聊消息 > 文本消息 即可，回调事件中会返回 Reaction 信息。 |
| 消息类型 | 是 | 需要回调的类型： - 聊天消息：发送成功的消息，包括通过 SDK 和 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 发送的消息。 |
回调路由说明
回调路由用于在同一个 App Key 下，将不同消息按环境维度分别投递到不同的回调地址。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 回调环境 | 是 | 回调环境仅支持字母和数字，长度不超过 8 个字符。默认为 default，不可删除。 |
| 回调地址 | 否 | 回调地址最大长度不超过 512 个字符。为空时表示该环境不走回调。 |
回调路由的匹配规则如下：
- 消息类回调：按消息中携带的回调环境值进行路由，精确匹配当前阶段的有效路由。
- 事件类回调：固定使用
default环境对应的回调地址，不参与环境匹配。
其他配置规则（如数量限制、双阶段路由建议、消息与路由的匹配等）与发送前回调一致，详见上文 回调路由配置。
高级过滤
| 参数 | 是否必需 | 描述 |
|---|---|---|
| From ID | 否 | 消息发送方或操作者的用户 ID。每行一个，最多 50 条。设置后，仅针对该用户发送的消息及执行的操作（如好友、群组或聊天室相关操作）进行回调。不指定则不限制。 |
| To ID | 否 | 单聊消息或事件接收方的用户 ID。每行一个，最多 50 条。不指定则不限制。 |
| 群组/聊天室 ID | 否 | 群组或聊天室 ID。每行一个，最多 50 条。设置后，仅针对该群组或聊天室中的消息或事件进行回调。不指定则不限制。 |
| 扩展字段中的 Key | 否 | 消息扩展字段中的属性 Key。每行一个，最多 50 条。设置后，仅针对包含该属性 Key 的消息进行回调。不指定则不限制。 |
高级过滤配置示例
| 场景 | 配置方式 | 效果 |
|---|---|---|
| 仅对单聊回调 | 设置 From ID 和 To ID | 指定发送方向接收方发送单聊消息或执行操作（如删除好友）时触发回调。例如，From ID 为 test1，To ID 为 test2，则 test1 向 test2 发送单聊消息时收到回调。 |
| 仅对群组/聊天室回调 | 仅设置 群组/聊天室 ID | 仅在指定的群组或聊天室中发送消息或执行操作时触发回调。例如，群组 ID 设为 228978，则仅在该群组中发送消息时收到回调。 |
| 仅对群组中特定用户回调 | 设置 From ID 和 群组/聊天室 ID | 仅当群组或聊天室中的指定用户发送消息或执行操作时触发回调。例如，From ID 为 test1，群组 ID 为 228978，则仅 test1 在该群组中发送消息时收到回调。 |
提示
若 From ID、To ID 和 群组/聊天室 ID 同时设置，则发送方向接收方发送单聊或群聊消息时 不会收到回调（二者互斥）。
发送后回调失败告警配置
发送后回调若在一定时间内达到累计失败次数会封禁该 app 的回调规则。为及时了解发送后回调的失败次数，进行相应处理，你可以设置发送后回调告警，避免 app 的回调规则被封禁。
在 消息回调 页面，点击回调规则列表右上方的 回调失败告警。在弹出的对话框中，配置告警参数。
| 参数 | 是否必需 | 描述 |
|---|---|---|
| 告警开关 | 是 | 是否开启发送后回调失败告警功能。 |
| 告警策略 | 是 | - 告警间隔：触发告警的时间间隔，单位为 5 分钟。 - 触发次数：告警间隔内触发告警的回调失败次数。 |
| 邮箱地址 | 是 | 接收发送后回调失败告警的邮箱地址。一次最多可输入 20 个，每行一个。 |