Post-messaging Callback

The Post-messaging Callback service supports synchronizing message data from one-to-one chats, groups, ultra groups, chatrooms, discussion groups (deprecated), and customer service (deprecated) to the specified application server. When the received message is an image or video, if you need to obtain the file information, you can download it via the provided URL, with the file storage valid for 6 months.

Use Case Examples:

• Chat History Storage: By enabling this service, you can synchronize user-sent messages to the application server in real-time for storage.
• Data Migration: Achieve a smooth migration from a third-party communication cloud service. When your new client (integrated with the client SDK) sends messages to the old client (integrated with the original third-party SDK), the server will call the corresponding service interface of the original third-party through the Post-messaging Callback service to send messages to the specified old client (integrated with the original third-party SDK). For details, refer to Smooth Migration.

Enabling the Service

Before using the Post-messaging Callback feature, ensure that the service has been enabled for the current App Key. For details, refer to Message Management Service Configuration.

When enabling the service, configure a callback receiving address that is accessible. If your network has IP access restrictions, make sure to configure the IP allowlist; otherwise, the server callback cannot be received normally.

Limitations and Notes

• Messages Containing Sensitive Words:

  • Built-in sensitive word services and third-party moderation services (e.g., Shumei) can set sensitive words for blocking messages. If a message is not delivered to the recipient due to containing such sensitive words, the server will not synchronize this message to the application server by default. If you need to route messages containing blocked sensitive words to the application server, you can enable the Blocked Message Callback to App Server feature in the Basic features interface of the RC Console.
  • If replacement of sensitive words is configured in the built-in sensitive word service, the sensitive words in the message will be replaced with the set content before being synchronized to the application server. To obtain the original content, refer to the knowledge base How to Get the Original Message Content When Using Built-in Sensitive Words, IM Content Moderation, and Message Callback Services?.

• Messages Sent via Server API Are Not Routed by Default:

  • Messages sent by calling the Server API interface are not routed through the Post-messaging Callback service by default. To modify this behavior, enable the Enable Server API Message Delivery Callback service on the Basic features page in the Console.

• Status Messages in One-to-One Chats Are Not Routed by Default: Status messages in one-to-one chat sessions are not synchronized to the application server by default. This includes the following scenarios:

  • Predefined status messages sent automatically by the client to one-to-one chat sessions, such as "Typing Status" messages. For details, refer to Message Type Overview.
  • Status messages sent actively by the client by calling the message sending interface, including predefined status messages or custom status messages.
  • Any messages sent by calling the Server API interface Send One-to-One Status Message.
  • To enable routing for the above status messages, you can enable the One-to-One Status Message Routing feature in the RC Console under Configuration > Chat settings > Basic features > One-to-One and Group Chats. Note that if the client uses the "Typing Status" feature in one-to-one chat sessions, the typing status messages will also be routed and stored in the message log. Please enable this feature cautiously due to the large message volume. If the Enable Server API Message Delivery Callback service is not enabled, only status messages sent by the client will be routed.

• Messages That Are Never Routed: Regardless of whether the Enable Server API Message Delivery Callback service is enabled, messages sent via the following interfaces are never routed:

  • /message/online/broadcast.json, refer to Broadcast to online users.
  • /message/broadcast.json, refer to Broadcast to Users.
  • /push.json, refer to Push by Tag, Push by Application Package Name, Push-only Notification.
  • /push/user.json, refer to Push to a Single User.

• Changes to Message Extensions in One-to-One and Group Chats Are Routed:

  • If changes are made to message extensions in one-to-one or group chats, the server will generate a message of type RC:MsgExMsg. This new message is only used for Post-messaging Callback synchronization and will not be synchronized to the client SDK. The new message ID is generated by the server, and the originalMsgUID field will carry the MsgUID of the original message.
  • Note that extension data carried when sending the message cannot be obtained through Post-messaging Callback.

• Changes to Message Extensions in Ultra Groups Are Not Routed by Default:

  • After August 11, 2022, changes to message extensions in ultra group operations can be synchronized to your specified application server. Considering the high frequency of message extensions, which may generate a large number of messages, the IM server does not perform Post-messaging Callback by default. If needed, submit a ticket to adjust whether Ultra Group Message Extensions Are Routed. After enabling the service, if changes are made to ultra group message extensions, the server will generate a message of type RC:MsgExMsg. This new message is only used for Post-messaging Callback synchronization and will not be synchronized to the client SDK. The new message ID is generated by the server, and the originalMsgUID field will carry the MsgUID of the original message.
  • Note that extension data carried when sending the message cannot be obtained through Post-messaging Callback.

• Changes to Message Content in Ultra Groups Are Routed: After August 11, 2022, changes to message content by app users in ultra groups will be automatically synchronized to the application server. After a user modifies a specified message in an ultra group, the server will generate a new message while retaining the original message content and ID. The new message is used for Post-messaging Callback synchronization, and its type is the same as the original message. The new message ID is generated by the server and will not be synchronized to the client SDK. The originalMsgUID field of the new message will carry the MsgUID of the original message.

Callback Method

Request Method: POST

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

The IM server will add signature parameters to the POST request URL. You can verify the caller's identity and data validity through the signature. For details, refer to Server Callback Signature. Note, the callback request path for Post-messaging Callback includes both timestamp and signTimestamp path parameters. Their values are the same, and it is recommended to only parse the signTimestamp parameter. The signTimestamp format is a Unix timestamp.

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:

Parameter	Type	Description
fromUserId	String	Sender user ID.
toUserId	String	Target ID, which is the client targetId. Depending on the channelType, it could be a one-to-one target ID, group ID, chatroom ID, customer service ID, etc.
objectName	String	Message type, e.g., text message RC:TxtMsg, image message RC:ImgMsg. Refer to Message Type Overview.
content	String	Sent message content. The message content structure refers to User Content Message Format or other built-in message type formats.
channelType	String	Conversation type. PERSON (one-to-one), PERSONS (discussion group), GROUP (group), TEMPGROUP (chatroom), CUSTOMERSERVICE (customer service), NOTIFY (system notification), MC (application public service), MP (public service), ULTRAGROUP (ultra group). This field corresponds to the ConversationType in the client SDK: 1 (one-to-one), 2 (discussion group), 3 (group), 4 (chatroom), 5 (customer service), 6 (system notification), 7 (application public service), 8 (public service), 10 (ultra group).
msgTimestamp	String	Server time when the server received the message from the client (milliseconds since 1970).
msgUID	String	The msgUID can be used to uniquely identify the message.
originalMsgUID	String	Original message ID, only valid for ultra group sessions. This field carries a valid value when modifying, extending, or deleting messages. You can query the original message content through this field. When modifying ultra group messages, if you need to recall the message on the server, you must use this ID.
sensitiveType	Int	Whether the message contains sensitive information. 0 means no, 1 means contains blocked sensitive words, 2 means contains replaced sensitive words. Note: Messages containing blocked sensitive words are not routed by default. You can submit a ticket to enable this. If not enabled (default), the sensitiveType value defaults to 0, which has no meaning. If enabled, you can use this attribute to determine if the text message contains sensitive words. Images and voice messages that fail moderation are marked as 1. Supported for one-to-one, group, and chatroom sessions. Other session types default to 0, and messages containing blocked sensitive words will not be delivered, only routed.
source	String	Identifies the source of the message, including: iOS, Android, HarmonyOS, Websocket, MiniProgram (mini program), PC, Server (sent via Server API, requires enabling the Enable Server API Message Delivery Callback feature).
busChannel	String	Conversation channel ID. When using the ultra group channel feature, the channel ID can be obtained through buschannel. If not used, this content is empty.
groupUserIds	String[]	Array of user IDs for group members receiving targeted group messages. Only group sessions (channelType is GROUP) support targeted group messages. If the specified users are not in the group, this field is empty. For non-targeted group messages, this field is empty.

Callback Request Example

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

POST /receive_message.php?appKey=someappKey&timestamp=1681202504348&signTimestamp=1681202504348&nonce=14314&signature=45beb7cc7307889a8e711219a47b7cf6a5b000e8 HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
User-Agent: RC/1.0

fromUserId=123&toUserId=456&objectName=RC%3ATxtMsg&content=%7B"content"%3A"hello"%7D&channelType=PERSON&msgTimestamp=1408710653491&msgUID=596E-P5PG-4FS2-7OJK&groupUserIds=["543","567"]

Responding to Callback Requests

tip

• As long as an HTTP 200 OK response is received, the server will consider the status synchronized.
• If the response times out after 5 seconds, the server will attempt to push 2 more times. If it still fails, this status will no longer be synchronized.
• If there are widespread timeouts in a short period, requests to your server will be temporarily stopped and will resume after 1 minute. In cases of abnormal network disconnection, synchronization will be delayed by 5 minutes.