이 페이지는 현재 영어로만 제공되며 한국어 버전은 곧 제공될 예정입니다. 기다려 주셔서 감사드립니다.

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.com
https://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.