All Users / Tags / UserID Push Callback
Feature Description
After enabling the push plugin, the push results can be forwarded to the app backend by configuring the basic callback.
Notes
This callback belongs to the event callback after downstream diffusion. To prevent a large number of callback requests from overwhelming the App backend, default QPS: 1000 times/s. Overfrequency callbacks will be retried after a delay. If you need to adjust QPS due to business requirements, you can submit a ticket to apply.
To enable this callback, you must configure the callback URL and enable the corresponding switch for this callback. For more information on the configuration method, see the Webhooks documentation.
During this callback, the Chat backend initiates an HTTP 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.
For additional safety-related concerns, please refer to the Third-Party Callback Overview: Security Considerations document.
API Description
Request URL sample:
In the following example, the callback URL configured in the App configuration is
https://www.example.comhttps://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json
Request parameters
Field | Description |
https | Request protocol is HTTPS. Request method is POST. |
www.example.com | Callback URL. |
SdkAppid | SDKAppID allocated by the Instant Messaging console at the time of Application creation. |
CallbackCommand | Fixed as: Push.AllMemberPush. |
contenttype | The request payload is fixed as JSON. |
Sample request packets
{"Events": [ // The Events array must contain 1–100 elements{"CallbackCommand": "Push.AllMemberPush","EventType": 1, // Event type. EventType = 1 indicates an offline push notification"TaskId": "657bf434_537529d8_2000005e80aa873_2780d131_bc614e", // Task ID for an all-member, tag-based, or single-recipient push"TaskTime": 1557481127, // Timestamp when the all-member push task was initiated, in seconds"EventTime": 1557481128, // Timestamp when the event occurred, in seconds"To_Account": "user2", // Recipient"PushPlatform": 4, // Push vendor"PushStage": 1, // Push stage"VendorInfo": {"FCM": { // Contains FCM vendor information when the message is sent to FCM"PushID": "xxxx","ChannelID": "xxxx","PushType": 0}},"ErrCode": 0, // Push event result code"ErrInfo": "OK" // Push event result description. May be empty},{"CallbackCommand": "Push.AllMemberPush","EventType": 1, // Event type. EventType = 1 indicates an offline push notification"TaskId": "657bf434_537529d8_2000005e80aa873_2780d131_9", // Task ID for an all-member, tag-based, or single-recipient push"TaskTime": 1557481127, // Timestamp when the all-member push task was initiated, in seconds"EventTime": 1557481129, // Timestamp when the event occurred, in seconds"To_Account": "user3", // Recipient"PushPlatform": 1, // Push vendor"PushStage": 1, // Push stage"VendorInfo": {"APNS": { // Contains APNs vendor information when the message is sent to APNs"PushID": "EF956E0D-0322-A33C-B546-85540B78BEE8","MutableContent": 1,"PushType": 2,"IsDowngraded": 1,"DowngradeReason": "voip token not exist"}},"ErrCode": 0, // Push event result code"ErrInfo": "OK" // Push event result description. May be empty}// Additional events...]}
Request packet fields
Field | Type | Description |
Events | Array [ Event Object ] | Batch callback content, containing data for up to 100 callback events (Event Object). |
Event Object Structure
Field | Type | Description |
CallbackCommand | String | Callback command. |
EventType | Integer | Event Type: EventType = 1 indicates offline push. EventType = 2 indicates online push. EventType = 3 indicates offline storage. |
TaskId | String | Task ID returned when the all-member push is sent. |
DataId | String | Custom identifier defined by the customer’s application. This field is omitted from the callback if it is not specified in the push request. |
TaskTime | Integer | Timestamp when the all-member push task was initiated, in seconds. |
EventTime | Integer | Timestamp when the event occurred, in seconds. |
To_Account | String | Recipient's UserID. |
PushPlatform | Integer | Push vendor (for online push EventType = 2/3 , vendor is not distinguished, default is 0 ): PushPlatform = 0 indicates unknown vendor. PushPlatform = 1 indicates Apple APNS push. PushPlatform = 2 indicates Xiaomi push. PushPlatform = 3 indicates Huawei push. PushPlatform = 4 indicates Google FCM push. PushPlatform = 5 indicates Meizu push. PushPlatform = 6 indicates OPPO push. PushPlatform = 7 indicates vivo push. PushPlatform = 8 indicates Honor push. |
DeviceType | Integer | Push device type (offline push events with EventType = 1 do not distinguish between device types, so this field is omitted for offline push events): PushPlatform = 0 indicates unknown device. PushPlatform = 1 indicates Apple APNS device. PushPlatform = 2 indicates Xiaomi device. PushPlatform = 3 indicates Huawei device. PushPlatform = 4 indicates Google FCM device. PushPlatform = 5 indicates Meizu device. PushPlatform = 6 indicates OPPO device. PushPlatform = 7 indicates vivo device. PushPlatform = 8 indicates Honor device. |
VendorInfo | Object | Note: This field is included only when PushStage = 1. Information for different push vendors is encapsulated in separate objects: APNs: Object. Included only when the push notification is sent to APNs. For details, see the APNs Object description. XiaoMi: Object. Included only when the push notification is sent to Xiaomi. For details, see the XiaoMi Object description. Huawei: Object. Included only when the push notification is sent to Huawei. For details, see the Huawei Object description. FCM: Object. Included only when the push notification is sent to FCM. For details, see the FCM Object description. Meizu: Object. Included only when the push notification is sent to Meizu. For details, see the Meizu Object description. OPPO: Object. Included only when the push notification is sent to OPPO. For details, see the OPPO Object description. VIVO: Object. Included only when the push notification is sent to vivo. For details, see the VIVO Object description. Honor: Object. Included only when the push notification is sent to HONOR. For details, see the Honor Object description. Hmony: Object. Included only when the push notification is sent to HarmonyOS. For details, see the Hmony Object description. |
PushStage | Integer | Push stage: PushStage = 1 indicates push sent. PushStage = 2 indicates push reached. PushStage = 3 indicates push clicked. |
ErrCode | Integer | Push event result: ErrCode = 0 indicates success. ErrCode non-zero indicates failure. |
ErrInfo | String | Push event result description. This field is omitted from the callback when the description is empty. |
APNs Object
Field | Type | Description |
PushID | string | Vendor push ID returned by APNs after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting APNs for troubleshooting. |
MutableContent | Integer | Parameter set when the push is initiated. Meaning: 1 indicates that the iOS 10+ notification extension is enabled. The default value is 0. |
InterruptionLevel | string | Parameter set when the push is initiated. Meaning: the notification interruption level for iOS 15+. The value must be one of active, critical, passive, or time-sensitive. For details, see APNs InterruptionLevel. |
ContentAvailable | Integer | Parameter set when the push is initiated. 1 indicates an iOS silent push, which does not display a notification banner. Apple recommends sending no more than 3 silent notifications per hour. For details, see APNs Background Notification. |
PushType | Integer | Push type requested when the push is initiated (this is the originally requested type; if a downgrade occurs, the push is actually delivered as a regular notification): 0: Regular notification. 1: Pass-through (silent) push. 2: VoIP push. 3: Live Activity push. |
IsDowngraded | Integer | Whether the push is downgraded to a regular notification. When a VoIP or Live Activity push is requested but the corresponding token does not exist or has expired, and no-downgrade is not set, the push is downgraded to a regular notification. 0: Not downgraded. 1: Downgraded. |
DowngradeReason | String | Downgrade reason, returned only when IsDowngraded = 1. Sample values: voip token not exist: The VoIP token does not exist. attributes_type: xxx, start token not exist: When starting a Live Activity, the start token for the corresponding attributes_type does not exist. laid: xxx, token not exist: When updating/ending a Live Activity, the token for the corresponding Live Activity ID does not exist. laid: xxx, token expired: When updating/ending a Live Activity, the token for the corresponding Live Activity ID has expired (more than 12 hours). |
XiaoMi Object
Field | Type | Description |
PushID | string | Vendor push ID returned by Xiaomi after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting Xiaomi Push for troubleshooting. |
ChannelID | string | Parameter set when the push is initiated. Meaning: the notification category (Channel) adaptation field for Xiaomi Push on MIUI 10 and later. For details, see Xiaomi Message Classification. When this field is not empty, it overrides the ChannelID configured in the push certificate in the console. |
HuaWei Object
Field | Type | Description |
PushID | string | Vendor push ID returned by Huawei after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting Huawei Push for troubleshooting. |
ChannelID | string | Parameter set when the push is initiated. Meaning: the notification channel field for Huawei Push on EMUI 10.0 and later. When this field is not empty, it overrides the ChannelID configured in the push certificate in the console. |
Category | string | Parameter set when the push is initiated. Meaning: the Huawei Push message category, used to identify the message type. For details, see category. When this field is not empty, it overrides the category configured in the push certificate in the console. |
FCM Object
Field | Type | Description |
PushID | string | Vendor push ID returned by FCM after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting FCM for troubleshooting. |
ChannelID | string | Parameter set when the push is initiated. Meaning: the notification channel field for Google Push on Android 8.0 and later. |
PushType | Integer | Push type: 0: Notification message. 1: Data message. |
Meizu Object
Field | Type | Description |
PushID | string | Vendor push ID returned by Meizu after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting Meizu Push for troubleshooting. |
NoticeMsgType | Integer | Parameter set when the push is initiated. Meaning: the Meizu Push message category. "0" indicates a public message, and "1" indicates a private message. For details, see Meizu Message Classification. When this field is not empty, it overrides the message category configured in the Meizu push certificate in the console. |
OPPO Object
Field | Type | Description |
PushID | string | Vendor push ID returned by OPPO after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting OPPO Push for troubleshooting. |
ChannelID | string | Parameter set when the push is initiated. Meaning: the NotificationChannel adaptation field for OPPO Push on Android 8.0 and later. When this field is not empty, it overrides the ChannelID configured in the push certificate in the console. |
Category | string | Parameter set when the push is initiated. Meaning: the OPPO Push message category, used to identify the message type. For details, see category. When this field is not empty, it overrides the category configured in the push certificate in the console. |
VIVO Object
Field | Type | Description |
PushID | string | Vendor push ID returned by vivo after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting vivo Push for troubleshooting. |
Category | string | Parameter set when the push is initiated. Meaning: the vivo Push message category, used to identify the message type. For details, see category. When this field is not empty, it overrides the category configured in the push certificate in the console. |
Honor Object
Field | Type | Description |
PushID | string | Vendor push ID returned by Honor after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting Honor Push for troubleshooting. |
Importance | string | Parameter set when the push is initiated. Meaning: the Honor Push message category. Valid values: LOW, NORMAL. For details, see Honor Message Classification. |
Hmony Object
Field | Type | Description |
PushID | string | Vendor push ID returned by HarmonyOS after a successful push. This field may be empty if the push fails. If the push is not received, you may need to provide this ID when consulting HarmonyOS Push for troubleshooting. |
PushType | Integer | Push type: 0: Regular notification. 7: Live View. |
Response packet example
{"ActionStatus": "OK","ErrorInfo": "","ErrorCode": 0 // 0 means callback success, 1 means callback error}
Response packet field description
Field | Type | Description |
ActionStatus | String | Processed Request Result: OK Signifies Successful Handling. FAILURE signifies unsuccessful execution. |
ErrorCode | Integer | Error Code. |
ErrorInfo | String | Error Description. |
