Feature Description

This API is used by the app backend to monitor a user’s one-to-one chat messages in real time, including:

• Records one-to-one chat messages in real time, for example, by recording a log or synchronizing the messages to other systems.
• Intercepts a user’s one-to-one chat requests.
• Modifies a user’s message content, for example, by filtering out sensitive words or adding custom information defined by the app.

Notes

• To enable this callback, you must configure the callback URL and enable the corresponding protocol for this callback. For more information on the configuration method, see Third-Party Callback Configuration.
• During this callback, 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 the SDKAppID of the app.
• If the callback before sending one-to-one chat messages and the callback after sending one-to-one chat messages are both enabled and muting is returned for the callback before sending one-to-one chat messages, the callback after sending one-to-one chat messages cannot 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 message body is modified during the callback before sending one-to-one chat messages, the callback after sending one-to-one chat messages will use the modified message for callback.
• For more security considerations, see Third-Party Callback Overview: Security Considerations.

Callback Trigger Scenarios

• An app user sends a one-to-one chat message on the client.
• The app admin sends a one-to-one chat message by calling the RESTful SendMsg API.

Callback Trigger Conditions

The IM backend has received a one-to-one chat message sent by a user but has not delivered the message to the target user.

API Call Description

Sample request URL

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

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

Request parameters

Sample request packets

{
    "CallbackCommand": "C2C.CallbackBeforeSendMsg", // The callback command that is run.
    "From_Account": "jared", // The sender of the message.
    "To_Account": "Jonh", // The recipient of the message.
    "MsgSeq": 48374, // The sequence number of the message.
    "MsgRandom": 2837546, // The random number of the message.
    "MsgTime": 1557481126, // The timestamp indicating when the message was sent. Unit: seconds. 
    "MsgKey": "48374_2837546_1557481126", // The unique identifier of the message. It is used by RESTful APIs to recall a one-to-one chat message.
    "MsgBody": [ // The body of the message. For more information, see the TIMMessage message object.
        {
            "MsgType": "TIMTextElem", // The text of the message.
            "MsgContent": {}
                "Text": "red packet"
            }
        }
    ]
}

Request packet fields

Sample response packet when chatting is allowed

In the following example, the user is allowed to chat and the IM backend does not modify the content of the to-be-delivered message.

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

Sample response packet when muting is enabled

In the following example, the user is muted. In this case, the IM backend does not deliver the to-be-delivered message, but returns error code 20006 to the message sender.

{
    "ActionStatus":"OK",
    "ErrorInfo":"",
    "ErrorCode": 1 // The value 1 indicates that the user is muted.
}

Sample response packet when the message content is modified

In the following example, the one-to-one chat message sent by the user is modified by adding custom information. In this case, the IM backend delivers the modified message. Based on this feature, the app backend can add special content such as the user level and title to the messages sent by users.
Example:

{
    "ActionStatus":"OK",
    "ErrorInfo":"",
    "ErrorCode": 0, // The parameter must be set to 0 so that the IM backend can deliver the modified message normally.
    "MsgBody": [ // The message modified by the app backend. If the app backend does not modify the message, the message sent by the user is used by default.
        {
            "MsgType": "TIMTextElem", // The text of the message.
            "MsgContent": {}
                "Text": "red packet"
            }
        },
        {
            "MsgType": "TIMCustomElem", // The custom information added to the message.
            "MsgContent": {}
                "Desc": " CustomElement.MemberLevel ", // The description of the message.
                "Data": " LV1" // The data of the message.
            }
        }
    ]
}

Response packet fields

References

• Third-Party Callback Overview
• [Invoke a Callback After Sending One-to-One Chat Messages] (https://intl.cloud.tencent.com/document/product/1047/34365)
• RESTful API: Sending a One-to-One Chat Message
• RESTful API: Batch Sending One-to-One Chat Messages