Overview

Third-party callback is an event callback of CommsEase available based on customer demands. To put it simply, it is the processing result of the client application server intervention event. For example, in the office scenario or scenario of accessing to third-party anti-spam service, after the sender sends a message, it is not delivered to the recipient. Instead, the CommsEase server sends a POST request to the application server, and determines whether to release based on the callback result returned by the application server. A comparison of message processing flow w/o callback is as follows:

Instructions and considerations

1. Third-party callbacks are based on the HTTP/HTTPS protocol.
   

2. After enabling the third-party callback, the CommsEase server will send the message content and user profile to the application server when the client is sending the message (note: it is the CommsEase server that initiates the HTTP-POST request to the application server), and the application server will determine whether the message can be sent and return the result, and the CommsEase server will then decide whether to deliver the message.
   Note: If messages are sent by server API, third-party callbacks will not be triggered.
   

3. The request is made by POST, and the message body is application/json; charset=utf-8. In the request for the business server, security is checked by adding CheckSum header, CheckSum = sha1(AppSecret + MD5 + CurTime), where AppSecret, MD5, CurTime are Strings. When verifying whether data has been tampered during transmission, you should verify whether the MD5 value has been updated and verify CheckSum through calculation. The AppSecret value is the developer's AppSecret (corresponding to the AppKey), and the MD5 value is a value calculated from the request body.

4. The CommsEase server will only request once, with a timeout of 2 seconds. If the request fails or times out, the CommsEase server will continue processing the business logic based on default callback results configured on the CommsEase console. You can update the default strategy for interface call failure by CommsEase Console> Select Application> IM Professional/Free> Feature Configuration> Third Party Callback.

5. After being blocklisted, you should first enable third-party callback before sending a message to the opposite side. If it is not allowed, SDK will return 403. Otherwise, SDK will return 7101.

6. In particular, for some callback types (such as sending peer-to-peer messages and team messages), you can set environment variables when sending messages, and the server will call back to different callback addresses based on different environments. Please contact the business administrator for the mapping relationship configuration between environment and callback address.

Callback protocol

Third party callbacks are based on HTTP/HTTPS protocol. To ensure data security, the developer is advised to use HTTPS, and related instructions are as follows:

1. Request HTTP Header

Header	Type	Description
AppKey	String	AppKey of the application
CurTime	Long	Current UTC timestamp, in milliseconds, counted from January 1, 1970, 0:00:00 (String)
MD5	String	MD5 value calculated based on the request body in the request
CheckSum	String	Check value
Content-Type	String	Type of request message body. The type should be application/json in general

MD5 example：

    String requestBody = "{}";
    String MD5 = CheckSumBuilder.getMD5(requestBody); //See Overview -> API checksum verification

Example of CheckSum value calculation:

    String AppSecret = "90ud57s67187";
    String MD5 = "9894907e4ad9de4678091277509361f7";
    String CurTime = "1440570500855"; ////The current UTC timestamp, in milliseconds counted since January 1, 1970 at 0:00:0 (String)
    String CheckSum = CheckSumBuilder.getCheckSum(AppSecret, MD5, CurTime); //See Overview -> API checksum verification

2. Request HTTP Body

All message bodies are in Json format, example:

    {
        "body": "Hello YunXin!" ,
        "eventType": 1,
        "fromAccount": "000266",
        "fromClientType": "WEB",
        "fromDeviceId": "617715aa8579db03f0cf054c199cc71b",
        "fromNick": "yj000266",
        "msgTimestamp": "1541560157286",
        "msgType": "TEXT",
        "msgidClient": "",
        "to": "005877",
        "fromClientIp":"115.211.51.45",
        "fromClientPort":"56802"
    }

//For attributes in Json, see the specific callback type

3. Response Format

Content-Type of the third-party callback response, Header needs to be set to: application/json; charset=utf-8

Response message body is in Json format, example:

    {
        "errCode":0,
        "responseCode": 20000,
        "modifyResponse": {},
        "callbackExt": "aa"
    }

Field description:

Field	Description
errCode	0: callback is passed and execution is allowed. 1: callback does not pass and the execution is canceled. If a legal custom error code (responseCode) has been set, the sender will receive such error code. Otherwise the sender will receive error code 403.
responseCode	1. Valid if errCode=1 2. The range is 20000-20099, other values are invalid and will be ignored 3. In particular, for third-party callback of message type (eventType=1, 2, 6, 22), error code can be set to 200, which indicates client shows the message is sent successfully but actually it is not.
modifyResponse	1. Valid for third-party callback of messages (eventType=1, 2, 6, 22), used to tamper with message content 2. JSON format, applicable to three fields of body, attach, and ext (all optional, if left blank, then no replacement). Length limit for normal messages sent also applies to these three fields. Example: {"body":"xxx","attach":"xxx","ext":"123"}. 3. Effect: The above three fields will be replaced in messages received by the recipient, of which the message sender is unaware. However, the messages received by the multi-client devices of the message sender have been updated as aforesaid. In addition, all stored offline messages, roaming messages, cloud history messages have also been updated as aforesaid. Therefore, all messages obtained from CommsEase server are all updated messages, regardless if they are obtained by the sender or recipient.
callbackExt	1. Valid for third-party callback of messages (eventType=1, 2, 6, 22), used to transmit extension information about third-party callbacks, with up to 1024 characters 2. Both sender and recipient of message can get this extension field (requiring SDK v7.7.0 or higher) 3. If errCode=1, then only message sender can get this field.

Type of third-party callback

Available third-party callback has the following types:

eventType	Features	Description
1	peer-to-peer message callback	When sending a peer-to-peer message with the SDK, after the parameter check is passed, first send a callback to the developer server, and only send the message after the callback is passed. Otherwise the message sending would fail.
2	Team message callback	When sending a team message with the SDK, after the parameter check is passed, first send a callback to the developer server, and only send the message after the callback is passed. Otherwise the message sending would fail.
3	User profile change callback	When changing user profile with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow the change after the callback is passed. Otherwise the change operation would fail.
4	Add friend callback	When adding a friend with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow adding the friend after the callback is passed. Otherwise the add friend operation would fail.
5	Remove friend callback	When removing a friend with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow removing the friend after the callback is passed. Otherwise the remove friend operation would fail.
6	Chat room message callback	When sending a peer-to-peer message with the SDK, after the parameter check is passed, first send a callback to the developer server, and only send the message after the callback is passed. Otherwise the message sending would fail.
7	Create team callback	When creating a team with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow creating the team after the callback is passed. Otherwise the operation would fail.
8	Callback - dismiss a team	When dismissing a team with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow dismissing the team after the callback is passed. Otherwise the operation would fail.
9	Callback - invitation to a team	When inviting a user with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow inviting the user after the callback is passed. Otherwise the operation would fail.
10	Callback - leave a team	When leaving a team with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow leaving the team after the callback is passed. Otherwise the operation would fail.
11	Callback - add a team administrator	When adding a team administrator with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow adding the administrator after the callback is passed. Otherwise the operation would fail.
12	Callback - remove a team administrator	When dismissing an administrator with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow dismissing the administrator after the callback is passed. Otherwise the operation would fail.
13	Callback - transfer a team	When transferring a team with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow transferring the team after the callback is passed. Otherwise the operation would fail.
14	Callback - kick someone out of a team	When kicking out a member with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow kicking out the member after the callback is passed. Otherwise the operation would fail.
15	Callback - update team profile	When updating team info with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow updating the info after the callback is passed. Otherwise the operation would fail.
16	Callback - update team member profile	When updating team member info with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow updating the info after the callback is passed. Otherwise the operation would fail.
17	Update other's team member profile callback	When updating other's team member info with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow updating the info after the callback is passed. Otherwise the operation would fail.
18	Callback - keep team members muted	When muting team members with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow muting the members after the callback is passed. Otherwise the operation would fail.
19	Callback - apply to join a team	When applying for joining a team with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow the joining application after the callback is passed. Otherwise the operation would fail.
20	Audio/video call callback	When initiate an audio/video call with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow initiating the call after the callback is passed. Otherwise the operation would fail.
21	Audio/video conference creation callback	When creating a audio/video conference with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow creating the conference after the callback is passed. Otherwise the operation would fail.
22	Superteam message callback	When sending a superteam message with the SDK, after the parameter check is passed, first send a callback to the developer server, and only send the message after the callback is passed. Otherwise the message sending would fail.
23	Superteam invitation callback	When inviting a user to join the superteam with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow inviting the user after the callback is passed. Otherwise the operation would fail.
24	Callback - kick someone out of a superteam	When kicking out a superteam member with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow kicking out the member after the callback is passed. Otherwise the operation would fail.
25	Callback - leave a superteam	When leaving a superteam with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow leaving the superteam after the callback is passed. Otherwise the operation would fail.
26	Update Superteam member profile callback	When updating Superteam info with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow updating the info after the callback is passed. Otherwise the operation would fail.
27	Callback - update Superteam member profile	When updating Superteam member info with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow updating the info after the callback is passed. Otherwise the operation would fail.
28	Callback - apply to join a superteam	When applying for joining a superteam with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow the joining application after the callback is passed. Otherwise the operation would fail.
29	Add Superteam administrator callback	When adding a team administrator with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow adding the administrator after the callback is passed. Otherwise the operation would fail.
30	Dismiss Superteam administrator callback	When dismissing an administrator with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow dismissing the administrator after the callback is passed. Otherwise the operation would fail.
31	Mute Superteam callback	When muting a superteam with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow muting the superteam after the callback is passed. Otherwise the operation would fail.
32	Mute Superteam member callback	When muting Superteam members with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow muting the members after the callback is passed. Otherwise the operation would fail.
33	Update other's Superteam member profile callback	When updating other's team member info with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow updating the info after the callback is passed. Otherwise the operation would fail.
34	Transfer Superteam callback	When transferring a superteam with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow transferring the team after the callback is passed. Otherwise the operation would fail.
35	Callback - recall a message	When recalling a p to p or team message with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow recalling the message after the callback is passed. Otherwise the operation would fail.
36	Callback - log in	When logging in with the SDK, after the parameter check is passed, first send a callback to the developer server, and only allow logging in after the callback is passed. Otherwise the operation would fail with 302 error code.

It is assumed that a third-party developer receives messages at the following address:

http://yunxinservice.com.cn/receiveMsg.action
As a general rule, all following third-party interfaces are assumed to be this interface.