Overview
Update time: 2023/09/25 09:38:48
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
-
Third-party callbacks are based on the HTTP/HTTPS protocol.
-
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. |
http://yunxinservice.com.cn/receiveMsg.action
As a general rule, all following third-party interfaces are assumed to be this interface.