Skip to main content

Callback Before Pushing Messages in Offline State

Function Description

Before messages are sent to the client, the App business server can receive requests for sending messages through this callback. The business server can intercept, modify, or add extra push information to the messages as needed.


  • To enable the callback, it is necessary to configure the callback URL and activate the corresponding switch for this callback protocol. Configuration methods can be found in the Callback Explanation document.
  • The direction of the callback is an HTTP/HTTPS POST request initiated by OpenIMServer to the App backend.
  • After receiving the callback request, the App business server needs to respond within the timeout period.

Scenarios That May Trigger This Callback

  • Group members leave the group.
  • Group members are kicked out of the group.
  • The group is disbanded.

Timing of the Callback

  • Before OpenIMServer is ready to push the message to the client.

Interface Description

Request URL Example

In the following example, the callback URL configured by the App is https://callbackurl.


Request Parameter Description

httpsRequest protocol is HTTPS, method is POST
https://callbackurlCallback URL
CallbackCommandFixed value: callbackBeforePushCommand
contenttypeFixed value: JSON
Header NameExample ValueMandatoryTypeDescription
operationID1646445464564RequiredstringoperationID for global link tracing

Request Packet Example

"callbackCommand": "callbackBeforePushCommand",
"platformID": 1,
"platform": "iOS",
"userIDList": ["user123", "user456"],
"title": "New Message",
"desc": "You have a new message",
"ex": "Extra push info",
"iOSPushSound": "default",
"iOSBadgeCount": true,
"signalInfo": "Signal data",
"clientMsgID": "msg123",
"sendID": "user789",
"groupID": "group123",
"contentType": 1,
"sessionType": 2,
"atUserIDList": ["user101", "user102"],
"content": "Hello, this is a test message"

Request Packet Field Explanation

callbackCommandstringCallback command, here for pre-message push callback
platformIDintPlatform ID (e.g., 1 for iOS, 2 for Android)
platformstringPlatform name (e.g., iOS, Android)
userIDListarrayList of user IDs who will receive this message
titlestringTitle of the push message
descstringDescription of the push message
exstringAdditional push information
iOSPushSoundstringiOS push sound setting
iOSBadgeCountboolWhether to change app badge count for iOS push
signalInfostringAdditional signal data carried with the push
clientMsgIDstringClient-generated message ID
sendIDstringUser ID of the sender
groupIDstringGroup ID, if it's a group message
contentTypeintType of message content
sessionTypeintSession type (e.g., 1 for single chat, 2 for group chat)
atUserIDListarrayList of user IDs mentioned in the message
contentstringContent of the message being sent

Response Packet Example

Allow Push

Allow the message to be pushed to the client.

"actionCode": 0,
"errCode": 0,
"errMsg": "Success",
"errDlt": "",
"nextCode": "",
"userIDList": ["user123", "user456"],
"offlinePushInfo": {
"title": "New Message",
"desc": "You have a new message",
"ex": "Extra push info",
"iOSPushSound": "default",
"iOSBadgeCount": true,
"signalInfo": "Signal data"

Response Packet Field Explanation

actionCode0Indicates if the business system's callback was executed correctly. 0 means the operation was successful.
errCode5001Custom error code, ranging between 5000-9999. Set when actionCode is not 0; set when nextCode is 1.
errMsg"An error message"Simple error message corresponding to the custom error code.
errDlt"Detailed error information"Detailed error information corresponding to the custom error code.
nextCode1Next step instruction, 1 means to refuse to continue executing, set when actionCode is 0.
userIDListarrayList of user IDs allowed to receive the message.
offlinePushInfoobjectObject containing offline push information.