Overview

Update time: 2023/09/25 01: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

  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

HeaderTypeDescription
AppKeyStringAppKey of the application
CurTimeLongCurrent UTC timestamp, in milliseconds, counted from January 1, 1970, 0:00:00 (String)
MD5StringMD5 value calculated based on the request body in the request
CheckSumStringCheck value
Content-TypeStringType of request message body. The type should be application/json in general

MD5 example:

java    String requestBody = "{}";
    String MD5 = CheckSumBuilder.getMD5(requestBody); //See Overview -> API checksum verification
javaExample 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

javaAll 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

javaContent-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:

FieldDescription
errCode0: 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.
responseCode1. 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.
modifyResponse1. 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.
callbackExt1. 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:

eventTypeFeaturesDescription
1peer-to-peer message callbackWhen 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.
2Team message callbackWhen 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.
3User profile change callbackWhen 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.
4Add friend callbackWhen 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.
5Remove friend callbackWhen 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.
6Chat room message callbackWhen 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.
7Create team callbackWhen 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.
8Callback - dismiss a teamWhen 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.
9Callback - invitation to a teamWhen 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.
10Callback - leave a teamWhen 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.
11Callback - add a team administratorWhen 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.
12Callback - remove a team administratorWhen 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.
13Callback - transfer a teamWhen 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.
14Callback - kick someone out of a teamWhen 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.
15Callback - update team profileWhen 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.
16Callback - update team member profileWhen 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.
17Update other's team member profile callbackWhen 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.
18Callback - keep team members mutedWhen 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.
19Callback - apply to join a teamWhen 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.
20Audio/video call callbackWhen 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.
21Audio/video conference creation callbackWhen 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.
22Superteam message callbackWhen 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.
23Superteam invitation callbackWhen 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.
24Callback - kick someone out of a superteamWhen 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.
25Callback - leave a superteamWhen 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.
26Update Superteam member profile callbackWhen 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.
27Callback - update Superteam member profileWhen 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.
28Callback - apply to join a superteamWhen 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.
29Add Superteam administrator callbackWhen 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.
30Dismiss Superteam administrator callbackWhen 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.
31Mute Superteam callbackWhen 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.
32Mute Superteam member callbackWhen 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.
33Update other's Superteam member profile callbackWhen 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.
34Transfer Superteam callbackWhen 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.
35Callback - recall a messageWhen 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.
36Callback - log inWhen 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.
Was this page helpful?
Yes
No
  • Overview
  • Instructions and considerations
  • Callback protocol
  • 1. Request HTTP Header
  • 2. Request HTTP Body
  • 3. Response Format
  • Type of third-party callback