本文档已不再维护，新版文档见：回调功能。

消息回调，即IM服务器会在事件发生之前或之后，向客户的应用服务器发送请求，应用服务器可以据此进行必要的数据同步（发送后回调），或者根据业务需求干预事件的后续处理流程（发送前回调）。

从处理角度看，回调分为以下两类：

• 发送前回调：回调的主要目的在于让 App 后台可以干预该事件的处理逻辑，IM服务器会根据回调返回码和返回值确定后续处理流程。
• 发送后回调：回调的主要目的在于让 App 后台实现必要的数据同步，IM服务器忽略回调返回码。

应用服务器可以通过发送前回调实时监控用户的聊天消息，包括：

• 对聊天消息进行实时同步；
• 拦截用户的消息请求。可拦截所有类型的消息，包含文本、图片、自定义消息等；

IM 服务器收到用户发送的单聊消息之后、将该消息下发给目标用户之前。

以下是发送前回调功能说明，在高并发可用性的基础上的使用限制说明，请按照此限制正确使用回调。

• 要启用消息回调，必须在管理后台开通消息回调服务，并配置回调规则和URL。
• 回调的方向是环信 IM 服务器向应用服务器发起 HTTPS POST 请求。
• 若同时设置了消息发送前和发送后两种回调，且消息发送前回调返回拒绝，则消息发送后回调将不会被触发。
• 发送前回调只对客户端发送的消息有效，不包含REST发送的消息。对同一个 APP 可以针对不同类型的消息（“TEXT”,“IMAGE”, “VIDEO”,“LOCATION”,“VOICE”和“FILE”）做配置；规则支持选择两种以上消息类型同时回调至一个指定服务器地址，在接收到消息后，可以区分消息的类型（详情查看API文档）。
• 当环信服务器执行发送前回调后，没有返回valid状态或者返回其他错误码时，当条消息会根据默认设置处理，不会再重试；后续消息依然正常执行回调。
• 消息发送到应用服务器后，应用服务器需要返回 HTTP 应答码 200，同时返回 valid 属性，根据 valid 状态决定是否进行下发。

规则说明：

• 规则可以有多条，每个规则的名称必须是唯一的。
• 环信 IM 服务器发送前回调应用服务器的超时时间默认为 200 ms，支持自定义“超时时间”。如果回调超时无应答，消息默认会正常下发，支持修改消息处理逻辑。
• 目前支持发送前回调的消息类型包括：文本，图片，视频，位置，语音，文件，自定义消息。

采用 POST 方式，正文部分为 JSON 格式的字符串，字符集为 UTF-8。

Request Body

请求示例

{
    "callId":"",
    "eventType":"chat_offline",
    "timestamp":0,
    "chat_type":"groupchat", 
    "group_id":'',
    "from":"",
    "to":"",
    "msg_id":"",
    "payload":{
    // 具体的消息内容
    },
    "securityVersion":"",
    "security":""
}

Response Body 在返回值中查看data字段包含的信息

返回的结果示例：

{
     "valid": true,
    "code": "HX:10000",
     "payload":{
    // 具体的消息内容
    // 仅支持文本类型消息
    },
}

发送后回调经常用在App后台需要实现必要的数据同步的场景。比如：

• 针对客户消息的内容进行自动回复
• 在 APP 自己的服务端及时保存聊天历史

注：如果您对聊天消息没有时效性需求，可以直接通过免费的聊天记录拉取 REST API 获取聊天记录，无需使用发送后回调。

以下是发送后回调功能说明，在高并发可用性的基础上的使用限制说明，请按照此限制正确使用回调。

• 消息回调属于增值服务，请联系环信商务询问价格，或者直接注册环信console账号自助付费开通。
• 消息回调开通允许用户配置提供2个回调规则配额，如果需要再增加回调规则，需要联系环信商务。
• 消息回调规则设置成功后，即刻正常使用。
• 发送后回调范围，所有上行消息有效（包含REST发送的消息），包含单聊/群聊；如果 APP 开通了反垃圾/敏感词过滤，被识别的消息会在服务器被拦截并禁止发送，将不会回调。
• 发送后回调接收延时，是指环信服务器接收到客户端上行消息、再将消息成功回调至客户指定服务器地址的时间间隔。消息接收延时保障是99.95% 的消息在30s内。
• 发送后回调对同一个 APP 可以针对不同类型的消息（chat 和 chat_offline）做配置，如果 APP 同时需要 chat 和 chat_offline 两种消息，建议区分回调地址。当然，规则也可以把这两种消息同时回调至一个指定服务器地址，在接收到消息后，可以对 eventType 做判断，区分消息的类型。
• 发送后回调重试，当环信服务器执行发出回调后，响应状态码非200，认为是指定服务器有网络或者其他因素导致失败，记录一次失败，然后立即重试，若再次失败，再记录一次失败，重试失败后不会再重试。30秒内累计90次失败，会对应封禁该 APP 回调规则，5分钟后自动解封。重试失败以及封禁期间的回调不会自动补录，可以下载历史消息文件自行补充。
• 指定服务器收到回调消息后，向环信服务器发出响应内容不能超过1000长度，如果连续发送超长的响应内容，会导致回调规则封禁，只能手动解除，需要用户手动重新设置。

APPKEY 可以配置回调规则的数据格式，可以配置多个回调规则（默认最多开通2个规则），开通服务后才允许用户配置，前往Console后台配置：

环信对回调地址http，https均支持。

这个消息跟通过 REST 导出聊天记录查询到的消息一致。比如：一个用户（u1）给另一个用户（u2）发送消息，那么就会产生一条 chat 消息，与接收方是否在线无关。接收到的消息里面 from 为 u1，to 为 u2。一个用户（u1）给一个群（g1）发送消息，那么会产生一条 chat 消息，接收到的消息里面 from 为 u1，to 为 g1，且返回值包含 group_id 字段。

APP 可以根据这个消息做 APNS 推送等个性化的推广。例如：给一个用户发送消息，如果用户不在线，那么会产生一条离线消息。如果给一个群发送消息，那么群里有几个用户不在线，就会产生几条离线消息，那么这几条离线消息的to为接收消息用户的id，并不是群组id。

• 如果APP只需要用户的聊天记录，那么配置chat类型消息的回调即可。
• 如果APP只需要针对离线消息做APNS推送等推送，那么配置chat_offline类型的消息回调即可。
• 如果APP同时需要用户的聊天记录也需要针对离线消息做处理，那么需要同时配置chat和chat_offline两种类型的消息回调。

目前支持 HTTP/HTTPS 方式的回调，采用 POST 方式，正文部分为 JSON 格式的字符串，字符集为 UTF-8。

回调时，会对发送的正文做 MD5 签名。环信这边 MD5 使用的是org.apache.commons.codec.digest.DigestUtils#md5Hex。

APP 的响应内容不能超过1000个字符。

{
    "callId":"",
    "eventType":"chat_offline",
    "timestamp":0,
    "chat_type":"groupchat", 
    "group_id":'',
    "from":"",
    "to":"",
    "msg_id":"",
    "payload":{
    // 具体的消息内容
    },
    "securityVersion":"",
    "security":""
}

Payload 数据格式说明。

环信不验证回调响应的response内容，只要您服务器给我们返回http状态码是200即可。