IM即时通讯 > 服务端API文档 > 第三方回调

第三方回调

功能概述

    第三方回调是云信一项基于客户需求开放的事件回调能力。简单来讲，就是由客户应用服务器干预事件处理的结果。例如在企业办公场景、接入第三方反垃圾服务场景下，客户需要在发送方发送消息时，不直接投递给接收方。而通过云信服务器向应用服务器发出请求，根据返回的回调结果，放行后方可投递。不回调和回调的消息处理流程对比如下：

说明:

1、第三方回调基于HTTP/HTTPS协议。
2、业务方开通了第三方回调服务时，云信服务器会在客户端发送消息时，将消息内容和用户信息发往业务方服务器，由业务方服务器端判断消息是否可以发送，根据业务方服务器返回的结果，云信服务器再选择是否投递消息。
3、请求方式为POST，消息体为JSON类型，在请求业务方服务器时，会通过增加CheckSum头来进行安全校验，CheckSum = sha1(AppSecret + MD5 + CurTime)， 其中AppSecret 、MD5、CurTime均为String类型。在验证数据是否在传输过程中被篡改时，需要计算验证MD5值是否被修改，以及计算验证CheckSum。AppSecret值为开发者的AppSecret(对应AppKey)， MD5值为根据request body计算出来的值。
4、云信服务器只会请求一次，超时时间为2秒，如果请求失败或者超时，云信服务器会使用业务方配置的默认回调结果继续处理业务逻辑

回调协议格式

    第三方回调基于HTTP/HTTPS协议，为保证数据安全，建议开发者使用HTTPS，协议相关说明如下：

1、请求Http Header说明

Header类型说明
AppKey String 应用的AppKey
CurTime Long当前UTC时间戳，从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String)
MD5String根据请求中的request body计算出来的MD5值
CheckSumString校验值
Content-TypeString请求消息体类型，一般为：application/json
MD5值计算举例：

    String requestBody = "{}";
    String MD5 = CheckSumBuilder.getMD5(requestBody); //参考 接口概述 -> API checksum校验 部分
CheckSum值计算举例：

    String AppSecret = "90ud57s67187";
    String MD5 = "9894907e4ad9de4678091277509361f7";
    String CurTime = "1440570500855";  ////当前UTC时间戳，从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String)
    String CheckSum = CheckSumBuilder.getCheckSum(AppSecret, MD5, CurTime); //参考 接口概述 -> API checksum校验 部分

2、请求Http Body说明

消息体统一为Json格式，示例：

    {
        "body": "Hello 云信！",
        "eventType": 1,
        "fromAccount": "000266",
        "fromClientType": "WEB",
        "fromDeviceId": "617715aa8579db03f0cf054c199cc71b",
        "fromNick": "yj000266",
        "msgTimestamp": "1541560157286",
        "msgType": "TEXT",
        "msgidClient": "",
        "to": "005877"
    }

//Json中的属性请参考具体的回调类型

3、响应格式说明

第三方回调响应的Content-Type Header需要设置为：application/json; charset=utf-8

响应消息体为Json格式，示例：

    {
        "errCode":0 
    }

errCode定义：

errCode说明
0回调通过，允许执行。
1回调不通过，取消执行，客户端会收到403错误码。

第三方回调事件类型

支持的回调事件类型如下：

eventType功能说明
1P2P消息回调通过SDK发送P2P消息时，参数检查通过后先回调开发者服务器，回调通过后才发送消息，否则消息发送失败。
2群组消息回调通过SDK发送群组消息时，参数检查通过后先回调开发者服务器，回调通过后才发送消息，否则消息发送失败。
3用户资料变更回调通过SDK变更用户资料时，参数检查通过后先回调开发者服务器，回调通过后才允许变更，否则变更失败。
4添加好友回调通过SDK添加好友时，参数检查通过后先回调开发者服务器，回调通过后才允许添加，否则添加失败。
5删除好友回调通过SDK删除好友时，参数检查通过后先回调开发者服务器，回调通过后才允许删除，否则删除失败。

假设第三方开发者的消息接收地址为：

http://yunxinservice.com.cn/receiveMsg.action
以下的第三方接口均假设为此接口，不再赘述。

会话消息回调

1.1 HTTP示例：

POST /receiveMsg.action HTTP/1.1
Host: yunxinservice.com.cn
AppKey: 158983881e092b052194d219453d6542
CurTime: 1541583920979
MD5: e89c284a5ad9a76b3176e23108920f81
CheckSum: 6f08c5ee2dd16a5fc34a12005e5d5f1411e657a1
Content-Type: application/json
Cache-Control: no-cache

{"body":"123456","eventType":1,"fromAccount":"000266","fromClientType":"WEB","fromDeviceId":"617715aa8579db03f0cf054c199cc71b","fromNick":"yj000266","msgTimestamp":"1541560157286","msgType":"TEXT","msgidClient":"","to":"005877"}

1.2 cURL示例：

curl -X POST \
  http://yunxinservice.com.cn/receiveMsg.action \
  -H 'appkey: 158983881e092b052194d219453d6542' \
  -H 'cache-control: no-cache' \
  -H 'checksum: 6f08c5ee2dd16a5fc34a12005e5d5f1411e657a1' \
  -H 'content-type: application/json' \
  -H 'curtime: 1541583920979' \
  -H 'md5: e89c284a5ad9a76b3176e23108920f81' \
  -d '{"body":"123456","eventType":1,"fromAccount":"000266","fromClientType":"WEB","fromDeviceId":"617715aa8579db03f0cf054c199cc71b","fromNick":"yj000266","msgTimestamp":"1541560157286","msgType":"TEXT","msgidClient":"","to":"005877"}'

1.3 消息体中的JSON字段说明：

回调消息中并不是每个字段都会一定抄送，请注意对各字段的判空处理。
名称类型必须说明
eventType Integer是值为1，表示是P2P消息回调；
值为2，表示是群组消息回调
fromAccount String是消息发送者的用户账号
fromNick String否发送方昵称
fromClientType String是发送客户端类型： AOS、IOS、PC、WINPHONE、WEB、REST
fromDeviceId String是发送设备id
to String是若eventType为1，则to为消息接收者的用户账号，字符串类型；
若eventType为2，则to为tid，即群id，可转为Long型数据
msgTimestamp String是消息发送时间
msgType String是会话具体类型PERSON、TEAM对应的通知消息类型：
TEXT ：文本消息
PICTURE ：图片消息
AUDIO ：语音消息
VIDEO ：视频消息
LOCATION ：地理位置
NOTIFICATION ：通知
FILE ：文件消息
NETCALL_AUDIO ：网络电话音频聊天
NETCALL_VEDIO ：网络电话视频聊天
DATATUNNEL_NEW ：新的数据通道请求通知
TIPS ：提示类型消息
CUSTOM ：自定义消息
msgidClient String否客户端消息Id
body String否消息内容
attach String否附加消息
ext String否消息扩展字段

用户资料变更回调

1.1 HTTP示例：

POST /receiveMsg.action HTTP/1.1
Host: yunxinservice.com.cn
AppKey: 158983881e092b052194d219453d6542
CurTime: 1541583920979
MD5: e89c284a5ad9a76b3176e23108920f81
CheckSum: 6f08c5ee2dd16a5fc34a12005e5d5f1411e657a1
Content-Type: application/json
Cache-Control: no-cache

{"account":"yx0002","birth":"2009-11-30","clientType":"PC","deviceId":"4f716737-75dd-41cb-bc6c-d9516ff03f707bd899c82e64bdc8a5220c07c744","email":"555555@163.com","eventType":3,"ex":"","gender":1,"icon":"https://ss0.bdstatic.com/94oJfD_bAAcT8t7mm9GUKT-xh_/timg?image&quality=100&size=b4000_4000&sec=1552461348&di=536bb9721d145a07657df45a8da49321&src=http://img0.pconline.com.cn/pconline/1511/29/7257120_901_thumb.jpg","mobile":"18888888888","name":"0002","sign":"这是签名","timestamp":"1552461406587"}

1.2 cURL示例：

curl -X POST \
  http://yunxinservice.com.cn/receiveMsg.action \
  -H 'appkey: 158983881e092b052194d219453d6542' \
  -H 'cache-control: no-cache' \
  -H 'checksum: 6f08c5ee2dd16a5fc34a12005e5d5f1411e657a1' \
  -H 'content-type: application/json' \
  -H 'curtime: 1541583920979' \
  -H 'md5: e89c284a5ad9a76b3176e23108920f81' \
  -d '{"account":"yx0002","birth":"2009-11-30","clientType":"PC","deviceId":"4f716737-75dd-41cb-bc6c-d9516ff03f707bd899c82e64bdc8a5220c07c744","email":"555555@163.com","eventType":3,"ex":"","gender":1,"icon":"https://ss0.bdstatic.com/94oJfD_bAAcT8t7mm9GUKT-xh_/timg?image&quality=100&size=b4000_4000&sec=1552461348&di=536bb9721d145a07657df45a8da49321&src=http://img0.pconline.com.cn/pconline/1511/29/7257120_901_thumb.jpg","mobile":"18888888888","name":"0002","sign":"这是签名","timestamp":"1552461406587"}'

1.3 消息体中的JSON字段说明：

回调消息中并不是每个字段都会一定抄送，请注意对各字段的判空处理。
只抄送用户资料变更的字段
名称类型必须说明
eventType Integer是值为3，表示是用户资料变更回调
account String是用户账号
deviceId String是发送方设备id
clientType String是发送客户端类型： AOS、IOS、PC、WINPHONE、WEB、REST
name String否昵称
icon String否头像图标
sign String否签名
email String否email
birth String否生日
mobile String否手机号
gender Integer否用户性别，0表示未知，1表示男，2表示女
ex String否用户名片扩展字段
timestamp String是操作时间，字符串类型

好友关系变更回调

1.1 HTTP示例：

POST /receiveMsg.action HTTP/1.1
Host: yunxinservice.com.cn
AppKey: 158983881e092b052194d219453d6542
CurTime: 1541583920979
MD5: e89c284a5ad9a76b3176e23108920f81
CheckSum: 6f08c5ee2dd16a5fc34a12005e5d5f1411e657a1
Content-Type: application/json
Cache-Control: no-cache

{"eventType":4,"fromAccount":"yx0001","fromClientType":"PC","fromDeviceId":"dd950b87-3c23-4c6d-863e-4c1fdeec1ecde54f68c09b22c55214cff7618ac5","msg":"加我加我","timestamp":"1552461598694","toAccount":"yx0002","verifyType":1}

1.2 cURL示例：

curl -X POST \
  http://yunxinservice.com.cn/receiveMsg.action \
  -H 'appkey: 158983881e092b052194d219453d6542' \
  -H 'cache-control: no-cache' \
  -H 'checksum: 6f08c5ee2dd16a5fc34a12005e5d5f1411e657a1' \
  -H 'content-type: application/json' \
  -H 'curtime: 1541583920979' \
  -H 'md5: e89c284a5ad9a76b3176e23108920f81' \
  -d '{"eventType":4,"fromAccount":"yx0001","fromClientType":"PC","fromDeviceId":"dd950b87-3c23-4c6d-863e-4c1fdeec1ecde54f68c09b22c55214cff7618ac5","msg":"加我加我","timestamp":"1552461598694","toAccount":"yx0002","verifyType":1}'

1.3 消息体中的JSON字段说明：

回调消息中并不是每个字段都会一定抄送，请注意对各字段的判空处理。
注意区分添加好友和删除好友抄送的字段有所不同
名称类型必须说明
eventType Integer是值为4，表示是添加好友回调；
值为5，表示是删除好友回调
fromAccount String是发起者账号
toAccount String是接收者账号
fromDeviceId String是发送方设备id
fromClientType String是发送客户端类型： AOS、IOS、PC、WINPHONE、WEB、REST
verifyType Integer否添加好友时此字段必有；含义:1直接加好友，2请求加好友，3同意加好友，4拒绝加好友
msg String否添加好友时此字段有效；含义:加好友对应的请求信息
timestamp String是操作时间，字符串类型

相关文档

相关产品