Pre-messaging Callback Service

The Pre-messaging Callback Service (formerly Template Routing) supports intercepting, filtering, and replacing messages sent within your app, making it suitable for scenarios where you need to integrate with your own or third-party content moderation services.

Currently, it supports one-to-one chat, group chat, chatroom, and ultra group business.

Overview of Pre-messaging Service

The Pre-messaging callback Service intercepts messages in transit based on the routing rules you configure in the Console. The intercepted message copy is first sent to your specified application server (App backend) instead of being directly delivered to the target user.

The App backend can handle the message through the callback response, including:

• Deciding whether to continue delivering the message (if no response is received within the timeout period, the IM service will automatically deliver the message by default)
• Deciding whether to continue delivering message extensions (only for ultra group conversation types; if no response is received within the timeout period, the IM service will automatically deliver by default)
• Deciding whether to continue delivering message modifications (only for ultra group conversation types; if no response is received within the timeout period, the IM service will automatically deliver by default)
• Modifying the message content directly using specified fields in the response body
• Modifying the push notification content (displayed in the notification bar) directly using specified fields in the response body
• Modifying the message extension KV directly using specified fields in the response body.

The IM service will decide whether to deliver the message, replace the message content, and how to replace it based on the response returned by the App backend.

Enabling the Service

Go to the Pre-messaging Callback Service page in the Console to enable the service. Prepayment is required to enable the service in the production environment.

If your network has IP access restrictions, be sure to configure the IP allowlist; otherwise, you will not be able to receive server callbacks normally.

The Pre-messaging Callback does not apply to messages sent via the Server API by default. If you need to filter messages sent via the IM Server API according to your configured routing rules and send them to the application server, you need to enable Server API message filtering for sensitive words on the Basic features page in the Console.

tip

• For services enabled after May 10, 2021, the replaceContent field in the response body is supported by default for message content replacement. Customers who enabled the service before May 10, 2021, must [submit a ticket] to request this feature.
• For services enabled after August 18, 2022, the replaceDisablePush, replacePushExt, and replaceExtraContent fields in the response body are supported by default for message content replacement. Customers who enabled the service before August 18, 2022, must [submit a ticket] to request this feature.

Creating Routing Rules

To use the Pre-messaging Callback Service, you need to create Pre-messaging Callback service rules (i.e., routing rules) in the Console.

After enabling the service, you can create routing rules on the Pre-messaging Callback Service page. A routing rule includes the following fields:

• Rule Name: Enter the rule name.
• Conversation Type: Select the conversation type to which the rule applies. Supported types include one-to-one chat, group chat, chatroom, and ultra group.
• Message Identifier: Enter the unique identifier for the message type. Only one identifier is supported per rule. For example, the identifier for the built-in text message type is RC:TxtMsg. See Message Type Overview for details. Custom message type identifiers are supported.
• Sender ID: Enter the sender's user ID or specify a rule to match the user ID. Once configured, this rule will only apply to the matched user.
• Receiver ID: Enter the conversation ID or specify a rule to match the conversation ID. Once configured, this rule will only apply to the matched conversation. The conversation ID for one-to-one chat is the receiver's user ID. The conversation ID for group chat and ultra group is the group ID. The conversation ID for chatroom is the chatroom ID.
• Callback URL: Enter the callback URL, which must be publicly accessible.

Notes

• Message Extensions for One-to-One and Group Chat Support Pre-messaging callback

  • Extension data carried when sending a message can be obtained via the extraContent parameter in the callback.
  • After August 11, 2022, changes to message extensions in ultra group business can be sent to the application server. After extending a message in an ultra group, the server generates a new message of type RC:MsgExMsg. This new message is only used for message routing synchronization and will not be synchronized to the client SDK. The new message ID is generated by the server, and the originalMsgUID field carries the original message's messageId. The content field contains the extension data for this change (see [Message Extension Function Message] for the structure). To enable the Pre-messaging Callback service for message extensions, you need to add a routing rule for the RC:MsgExMsg type in the Console.

• Ultra Group Message Extensions Support Pre-messaging Callback:

  • Extension data carried when sending a message can be obtained via the extraContent parameter in the callback.
  • After August 11, 2022, subsequent changes to message extensions in ultra group business can also be synchronized to the application server. After modifying the message extension in an ultra group, the server generates a new message of type RC:MsgExMsg. This new message is only used for message routing synchronization and will not be synchronized to the client SDK. The new message ID is generated by the server, and the originalMsgUID field carries the original message's messageId. The content field contains the extension data for this change (see [Message Extension Function Message] for the structure). To enable the Pre-messaging Callback service for message extensions, you need to add a routing rule for the RC:MsgExMsg type in the Console.

• Ultra Group Message Content Modification Supports Pre-messaging Callback: Ultra group messages can be modified after being sent (the message type cannot be modified). After August 11, 2022, changes made by App users to ultra group message content can be sent to the application server. After a user modifies a message, the server generates a new message while retaining the original message content and ID. The new message is only used for synchronization and has the same type as the original message, so no additional routing rules are needed. The new message ID is generated by the server and will not be synchronized to the client SDK. The originalMsgUID field in the new message carries the original message's messageId.

• Files in Media Messages Need to Be Retrieved Manually: For image or video messages, if you need to retrieve the image or video file information, you can download it via the URL carried in the message. The file storage is valid for 6 months.

• Can Be Used Simultaneously with Post-messaging Callback: The Pre-messaging Callback, Content Moderation, and Sensitive Word Filtering services can be used simultaneously with Post-messaging Callback. Messages rejected by these services will not be synchronized by the Post-messaging Callback service by default. To modify this default behavior, you can enable the Enable Routing for Messages Containing Sensitive Words feature in the RC Console under Configuration > Chat settings > Basic features > Security. After enabling this feature, messages containing blocked sensitive words will also be synchronized to the application server.

Callback Method

Request Method: POST

Data Format: application/x-www-form-urlencoded

The IM server will add a signature parameter to the POST request URL. You can verify the caller's identity and data validity through the signature. For details, see Server Callback Signature.

Callback Body Parameters

The HTTP request body data format for this callback service is application/x-www-form-urlencoded, containing the following HTTP form parameters:

Name	Type	Description
appKey	String	The app's App Key.
fromUserId	String	The sender's user ID.
targetId	String	The target conversation ID, which could be a one-to-one chat ID, group chat ID, chatroom ID, or ultra group ID depending on the conversation type.
toUserIds	String	A list of group member IDs (separated by commas). When sending a group-targeted message, this is the list of user IDs of the group members who will receive the message. For non-group-targeted messages, this field is empty.
msgType	String	The message type configured for the callback (including custom messages). See Message Type Overview for details.
content	Object	The message content in JSON format. If msgType is a built-in message type, the message content structure refers to User Content Message Format or other built-in message type formats. If msgType is a custom message type, refer to the custom message structure. This field can be modified via the callback response.
pushContent	String	The content displayed in the push notification bar when the message is sent. This content is displayed in offline push notifications. This field can be modified via the callback response.
disablePush	Boolean	Whether the message is silent. The default is false. When set to true, end users will not receive notification reminders when offline. This field can be modified via the callback response.
pushExt	String	Configures the push notification for the message, such as the notification title. See the server documentation for Sending Messages for details on pushExt. This property is invalid when disablePush is true. This field can be modified via the callback response.
expansion	Boolean	Whether the message is extensible. The default is false. When set to true, the end user can set extension information for this message after receiving it. This feature is supported in mobile SDK version 4.0.3 and web SDK version 3.0.7.
extraContent	Object	The content of the message extension, a JSON structure of key-value pairs, e.g., {"type":"3"}. The key can be up to 32 characters and supports uppercase and lowercase letters, numbers, and special characters + = - _. Chinese characters are not supported. The value can be up to 4096 characters. This field is only valid when expansion is true. This field can be modified via the callback response.
channelType	String	The conversation type. Supported conversation types include: PERSON (one-to-one conversation), PERSONS (discussion group conversation), GROUP (group conversation), TEMPGROUP (chatroom conversation), ULTRAGROUP (ultra group conversation).
msgTimeStamp	String	The server time when the server received the message from the client (in milliseconds since 1970).
messageId	String	The unique identifier of the message.
originalMsgUID	String	The original message ID, only valid for ultra group conversations. This field carries a valid value when modifying, extending, or deleting a message. You can query the original message content through this field. When modifying an ultra group message, you must use this ID if you need to recall the message on the server.
os	String	The source of the message, including: iOS, Android, HarmonyOS, Websocket, MiniProgram (mini-program), PC, Server.
busChannel	String	The conversation channel ID. If the message is from an ultra group channel, you can get the channel ID via busChannel. This field is empty when not in use.
clientIp	String	The user's current IP address and port, in the format: 192.168.6.124:80.

Callback Request Example

For example, the receiving address you configured on the service enablement page: http://example.com/receive_message.php

POST /receive_message.php?timestamp=1408710653491&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

appKey=123&content={"content":"123"}&fromUserId=fid123&targetId=tid123&msgType=RC:TxtMsg&messageId=596E-P5PG-4FS2-7OJK&msgTimeStamp=1408710653491&channelType=ULTRAGROUP&os=Server&busChannel=basketball

Responding to Callback Requests

After the message is sent to the application server, the application server needs to return an HTTP response code of 200 and specify the pass attribute value. The IM server will decide whether to deliver the message based on the pass status.

The HTTP request body data format for the response is application/json, containing a JSON object with the following structure:

Return Parameter Name	Type	Description
pass	Int	Service enabled before May 10, 2021, return status description: 1 means the message will be delivered normally; other values mean rejection. Service enabled after May 10, 2021, return status description: 0 means rejection, and the message will not be delivered. 1 means the message will be delivered normally, and if other Pre-messaging Callback conditions are met, they will continue to be executed. 2 means the message will be delivered normally, but if other Pre-messaging Callback conditions are met, they will not continue to be executed. Note: Customers who enabled the service before May 10, 2021, must submit a ticket to request the latest return status definition.
replaceContent	String	Optional, JSON structure, the message content to be replaced, e.g., to replace the content of a text message, pass {\"content\":\"replaced content\"}; for custom messages, standard JSON structure content replacement is supported, e.g., to replace the content in the msg field of a custom message, pass \"msg\":{\"content\":\"replaced content\"}. Custom messages support content replacement up to the sixth level of the structure. If not passed, no replacement will be performed.
replacePushContent	String	Optional, the replaced pushContent field content. If this field is not filled or an empty string is passed, the original value will be used by default.
replaceDisablePush	Boolean	Whether the message is silent. The default is false. When set to true, end users will not receive notification reminders when offline.
replacePushExt	String	Optional, the replaced pushExt field content. See the server documentation for Sending Messages for details on pushExt. If this field is not filled or an empty string is passed, the original value will be used by default.
replaceExtraContent	String	Optional, if a value is provided, it will replace the extraContent content. The data format is: {\"key1\":{\"v\":\"value1\"},\"key2\":{\"v\":\"value2\"}}. See the server documentation for Sending Messages for details on extraContent. The data size is limited as follows: The key supports uppercase and lowercase letters, numbers, and special characters + = - _. Chinese characters are not supported, with a maximum of 32 characters. The value can be up to 4096 characters.
extra	String	When the message is not delivered (i.e., pass is 0), this field is used to notify the sender of the message, e.g., the specific reason why the message could not be delivered. The data carried in this field will be returned to the sender via the client's "Sensitive Message Interception Callback" and placed in the extra field of the intercepted message details. Currently, it supports one-to-one chat, group chat, chatroom, and ultra group conversation types. The length cannot exceed 1024 characters. Client SDK version requirements: Web IMLib SDK ≧ 5.3.3, Android IM SDK version ≧ 5.2.5 (or maintenance versions 5.2.3.2 and above in the 5.2.3.x series).

Important

• Whether the replaceContent, replaceDisablePush, replacePushExt, and replaceExtraContent fields can be used in the response body is related to the service enablement date. Please read Enabling the Service carefully.
• If the data size exceeds the limit or the data format is incorrect, the message delivery will fail. It is recommended to keep replacePushExt within 1.5 KB. The total length of push-related fields must not exceed 3.8 KB. Exceeding this limit may cause push message failures on some third-party vendor channels. Push-related fields specifically refer to replacePushContent, replacePushExt, or the original value of the field if it is not replaced.
• If the response times out after 5 seconds, the server will try to push again up to 3 times. If it still fails, the IM service will deliver the message by default.
• If there is a large-scale timeout in a short period, the server will temporarily stop sending callback requests to your server and will continue after 90 seconds. In case of abnormal network disconnection, synchronization will be delayed by 5 minutes.

Response Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "pass": 1 }

Tips on Replacing Message Content

Replacing message content affects the local and server-side historical message records of both senders and receivers differently. Use this feature with caution.

tip

​- One-to-one Chat & Group Chat: After replacement, the sender's local and server-side history retain the original content, while the receiver's local and server-side storage reflects the replaced content. ​- Chatroom Messages: After replacement, the sender's local storage retains the original content, while the receiver's local storage shows the replaced content. Both sender and receiver server-side records store the replaced content.

• ​Ultra group Messages: After replacement, the sender's local storage retains the original content, while the server-side history stores the replaced content (thus fetching replaced content upon cross-device login). Receivers' local and server-side records both reflect the replaced content.