Invoke a Callback Before Sending One-to-One Messages

Feature Description

Through this callback, the app backend can monitor users’ one-to-one chat messages in real time, including:

• Recording one-to-one chat messages in real time (for example, recording the messages in a log or synchronizing them to other systems).
• Intercepting users’ one-to-one chat requests.
• Modifying users’ message content (for example, filtering sensitive words or adding app-defined custom information).

Precautions

• To enable this callback, you must configure the callback URL and toggle on the callback. For details on the configuration method, see Third-Party Callback Configuration.
• Callback direction: The IM backend initiates an HTTPS POST request to the app backend.
• After receiving the callback request, the app backend must check whether the SDKAppID contained in the request URL is consistent with its own SDKAppID.
• If the callback before sending one-to-one chat messages and the callback after sending one-to-one chat messages are both enabled and the callback before sending one-to-one chat messages returns muting, then the callback after sending one-to-one chat messages will not be triggered.
• If the callback before sending one-to-one chat messages and the callback after sending one-to-one chat messages are both enabled and the callback before sending one-to-one chat messages modifies the message body, then the callback after sending one-to-one chat messages will use the modified message for callback.
• For other security-related issues, see Third-Party Callback Overview: Security Considerations.

Callback Triggering Scenarios

• An app user uses a client to send a one-to-one chat message.
• The app admin sends a one-to-one chat message through the RESTful API (sendmsg).

Callback Triggering Time

The callback is triggered after the IM backend receives a one-to-one chat message sent by a user and before the IM backend sends the message to the target user.

API Description

Request URL example

In the following example, the callback URL configured by the app is https://www.example.com.
Example:

https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

Request parameters

Request packet example

{
    "CallbackCommand": "C2C.CallbackBeforeSendMsg", // Callback command
    "From_Account": "jared", // Sender
    "To_Account": "Jonh", // Recipient
    "MsgSeq": 48374, // Message sequence number
    "MsgRandom": 2837546, // Message random number
    "MsgTime": 1557481126, // Message sending timestamp, in seconds 
    "MsgBody": [ // Message body. See the TIMMessage message object.
        {
            "MsgType": "TIMTextElem", // Text
            "MsgContent": {
                "Text": "red packet"
            }
        }
    ]
}

Request packet fields

Response packet example (with chat allowed)

Allows the user to chat without modifying the content of the message to be sent.

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0 // 0 indicates that chat is allowed.
}

Response packet example (with muting enabled)

Mutes the user. Meanwhile, the message will not be sent, and the 20006 error code will be returned to the user (the message sender).

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 1 // 1 indicates muting.
}

Response packet example (with message content modified)

In the following response example, the one-to-one chat message sent by the user is modified (a custom message is added), and the IM backend will deliver the modified message. Based on this situation, the app backend can add some special content, such as the user level and title, to the message sent by the user.
Example:

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0, // The parameter value must be set to 0 so that the modified message can be normally delivered.
    "MsgBody": [ // The modified message by the app. If no modification is made, the message sent by the user is used by default.
        {
            "MsgType": "TIMTextElem", // Text
            "MsgContent": {
                "Text": "red packet"
            }
        },
        {
            "MsgType": "TIMCustomElem", // Custom message
            "MsgContent": {
                "Desc": " CustomElement.MemberLevel ", // Description
                "Data": " LV1" // Data
            }
        }
    ]
}

Response packet fields

References

• Third-party callback overview
• Callback after sending one-to-one chat messages
• RESTful APIs: Sending a one-to-one chat message
• RESTful APIs: Sending one-to-one chat messages in batches