第三方回调

功能概述

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

说明:

1、第三方回调基于HTTP/HTTPS协议。
2、业务方开通了第三方回调服务时,云信服务器会在客户端发送消息时,将消息内容和用户信息发往业务方服务器,由业务方服务器端判断消息是否可以发送,根据业务方服务器返回的结果,云信服务器再选择是否投递消息。
3、请求方式为POST,消息体为JSON类型,在请求业务方服务器时,会通过增加CheckSum头来进行安全校验,CheckSum = sha1(AppSecret + MD5 + CurTime), 其中AppSecret 、MD5CurTime均为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回调不通过,取消执行。

第三方回调事件类型

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

eventType功能说明
1P2P消息回调通过SDK发送P2P消息时,参数检查通过后先回调开发者服务器,回调通过后才发送消息,否则消息发送失败。

P2P消息回调

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

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、fromAccount、fromClientType、to、msgTimestamp、msgType
名称类型说明
eventType Integer值为1,表示是P2P消息回调
fromAccount String消息发送者的用户账号
fromNick String发送方昵称
fromClientType String发送客户端类型: AOS、IOS、PC、WINPHONE、WEB、REST
fromDeviceId String发送设备id
to String消息接收者的用户账号
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消息扩展字段