帮你快速理解、总结文档立即下载

离线推送消息属性设置

最近更新时间:2026-11-06 14:46:06
本文档已由 AI 辅助审校
我的收藏
当 App 进入后台或被杀进程后,IM 消息将通过各厂商推送通道(FCM、小米、华为、vivo、OPPO、荣耀、魅族、APNs、HarmonyOS Push 等)下发至终端设备。发送消息时,您可以通过推送配置设置通知栏标题、内容、点击透传数据,以及各厂商通道的推送特性(如消息分类、铃音、图片、私信模板等)。

选择推送配置结构

IM SDK 提供两种推送配置结构,请根据发送端平台选择:
发送端平台
推送配置结构
说明
Android、iOS
V2TIMPushInfo
推荐使用,详见 V2TIMPushInfo。
Android、iOS
V2TIMOfflinePushInfo
已废弃,仍可正常使用,详见 V2TIMOfflinePushInfo。
其他平台(C、C++、HarmonyOS、Flutter、React Native、uni-app、Unity 等)
V2TIMOfflinePushInfo
请继续使用此结构,详见 V2TIMOfflinePushInfo。

V2TIMPushInfo(Android / iOS 推荐)

注意:
IMSDK 9.1.x 及以上版本支持。

结构说明

V2TIMPushInfo 包含 4 个字段:
字段
类型
说明
是否在通知栏可见
title
String
通知栏标题。
可见
desc
String
通知栏内容。自定义消息必须填写。
可见
clickPayload
Android:byte[]
iOS:NSString
点击通知后传给 App 的透传数据,常用于页面跳转,建议使用 JSON 格式。
不可见
notification
String(JSON)
通知特性配置,如消息分类、铃音、图片、私信模板等。
不可见(但影响展示行为)
请按需选择用法:
基础用法:只设置 title、desc、clickPayload。消息分类等配置由 SDK 默认填充,适合大多数聊天场景。
高级用法:在基础用法的基础上设置 notification,自定义消息分类、铃音、图片、私信模板等。

基础用法

只需设置以下 3 个字段:
title:不填时使用默认标题(如发送者昵称或群名称)。
desc:不填时使用默认内容(如文本消息的文字)。自定义消息必须填写,否则不推送。
clickPayload:按业务需要填写,接收端点击通知后可获取。

SDK 默认配置

使用 V2TIMPushInfo 时,SDK 会按 IM 聊天场景自动填充以下配置,无需手动设置:
通道
默认配置
含义
华为
huawei.category = "IM"
即时通讯类消息
荣耀
honor.importance = "NORMAL"
服务通讯类消息
OPPO
oppo.category = "IM"
即时通讯类消息
vivo
vivo.category = "IM"
vivo.classification = 1
vivo.notifyType = 4
即时通讯类消息,响铃和振动
魅族
meizu.notifyType = 1
私信消息
FCM
googleFCM.priority = "high"
高优先级
HarmonyOS
harmony.category = "IM"
即时通讯类消息
说明:
如果不是 IM 聊天场景(例如营销通知),请参考 高级用法 覆盖对应字段。
小米、OPPO 的通知渠道(channelId)和私信模板(templateId)没有默认值,请按需在 notification 中设置。私信模板 ID 也可以在 IM 控制台配置,配置后无需修改代码。

用法示例

以下示例发送一条单聊消息。发送群消息时,userID 传空,groupID 传群 ID。
Android
iOS
Java
Kotlin
import com.tencent.imsdk.v2.V2TIMManager;
import com.tencent.imsdk.v2.V2TIMMessage;
import com.tencent.imsdk.v2.V2TIMPushInfo;
import com.tencent.imsdk.v2.V2TIMSendCallback;
import com.tencent.imsdk.v2.V2TIMSendMessageOption;
import java.nio.charset.StandardCharsets;

V2TIMMessage message = V2TIMManager.getMessageManager().createTextMessage("你好,在吗?");

V2TIMPushInfo pushInfo = new V2TIMPushInfo();
pushInfo.setTitle("张三");
pushInfo.setDesc("你好,在吗?");
pushInfo.setClickPayload("{\\"key\\":\\"value\\"}".getBytes(StandardCharsets.UTF_8));

V2TIMSendMessageOption option = new V2TIMSendMessageOption();
option.setPushInfo(pushInfo);

V2TIMManager.getMessageManager().sendMessage(message, "user_001", null, option,
new V2TIMSendCallback<V2TIMMessage>() {
@Override
public void onProgress(int progress) {
}

@Override
public void onSuccess(V2TIMMessage v2TIMMessage) {
}

@Override
public void onError(int code, String desc) {
}
});
import com.tencent.imsdk.v2.V2TIMManager
import com.tencent.imsdk.v2.V2TIMMessage
import com.tencent.imsdk.v2.V2TIMPushInfo
import com.tencent.imsdk.v2.V2TIMSendCallback
import com.tencent.imsdk.v2.V2TIMSendMessageOption

val message = V2TIMManager.getMessageManager().createTextMessage("你好,在吗?")

val pushInfo = V2TIMPushInfo()
pushInfo.title = "张三"
pushInfo.desc = "你好,在吗?"
pushInfo.clickPayload = "{\\"key\\":\\"value\\"}".toByteArray(Charsets.UTF_8)

val option = V2TIMSendMessageOption()
option.pushInfo = pushInfo

V2TIMManager.getMessageManager().sendMessage(message, "user_001", null, option,
object : V2TIMSendCallback<V2TIMMessage> {
override fun onProgress(progress: Int) {}
override fun onSuccess(v2TIMMessage: V2TIMMessage?) {}
override fun onError(code: Int, desc: String?) {}
})
OC
Swift
#import <ImSDK_Plus/ImSDK_Plus.h>

V2TIMMessage *message = [[V2TIMManager sharedInstance] createTextMessage:@"你好,在吗?"];

V2TIMPushInfo *pushInfo = [[V2TIMPushInfo alloc] init];
pushInfo.title = @"张三";
pushInfo.desc = @"你好,在吗?";
pushInfo.clickPayload = @"{\\"key\\":\\"value\\"}";

V2TIMSendMessageOption *option = [[V2TIMSendMessageOption alloc] init];
option.pushInfo = pushInfo;

[[V2TIMManager sharedInstance] sendMessage:message
userID:@"user_001"
groupID:nil
option:option
progress:nil
succ:^{
} fail:^(int code, NSString *desc) {
}];
import ImSDK_Plus

let message = V2TIMManager.sharedInstance().createTextMessage(text: "你好,在吗?")

let pushInfo = V2TIMPushInfo()
pushInfo.title = "张三"
pushInfo.desc = "你好,在吗?"
pushInfo.clickPayload = "{\\"key\\":\\"value\\"}"

let option = V2TIMSendMessageOption()
option.pushInfo = pushInfo

V2TIMManager.sharedInstance().sendMessage(message: message, userID: "user_001", groupID: nil, option: option, progress: nil, succ: {
}, fail: { code, desc in
})

高级用法

需要自定义消息分类、铃音、图片、私信模板等特性时,设置 notification 字段。

填写规则

notification 是一个 JSON 字符串,第一层为分组名(通用配置、平台或厂商通道),第二层为该分组的字段:
{
"ios": { "sound": "default" },
"huawei": { "category": "IM" }
}
按需填写:只填写需要的分组和字段。未填写的字段使用 SDK 默认值;已填写的字段覆盖对应的默认值,同一分组内的其他默认值仍保留。
按接收端生效:同一份配置可以同时包含多个分组,推送时按接收端实际使用的通道取用对应分组。例如 Android 发送端也可以填写 ios 分组,设置 iOS 接收端的铃音。
类型正确:布尔值使用 true / false,整数使用数字,不要加引号。
模板参数:commonConfig.tencentPushTemplateParam、xiaomi.templateParam、oppo.templateTitle、oppo.templateContent 直接传 JSON 对象即可,也支持传 JSON 字符串。
容错:字段名或类型错误不会导致消息发送失败,SDK 会忽略该字段并打印 warning 日志;notification 不是合法 JSON 时,按未填写处理。

用法示例

以下示例包含了 notification 的所有分组和字段,复制后删除不需要的字段即可使用:
{
"commonConfig": {
"image": "https://example.com/image.png",
"notificationMode": "notification",
"tencentPushTemplateId": "templateid",
"tencentPushTemplateParam": { "address": "1908 会议室", "time": "3 分钟" }
},
"android": {
"sound": "private_ring"
},
"ios": {
"pushType": 0,
"sound": "default",
"ignoreBadge": false,
"interruptionLevel": "active",
"enableBackgroundNotification": false,
"image": "https://example.com/image.png"
},
"harmony": {
"category": "IM",
"image": "https://example.com/image.png",
"ignoreBadge": false,
"sound": "alert.mp3",
"soundDuration": 10
},
"huawei": {
"category": "IM",
"image": "https://example.com/image.png"
},
"honor": {
"importance": "NORMAL",
"image": "https://example.com/image.png"
},
"xiaomi": {
"channelId": "im_channel",
"templateId": "P10032",
"templateParam": { "keywords1": "张三", "keywords2": "你好,在吗?" }
},
"oppo": {
"channelId": "im_channel",
"category": "IM",
"notifyLevel": 2,
"templateId": "oppoid",
"templateTitle": { "city": "北京" },
"templateContent": { "userName": "汤姆", "city": "深圳市" }
},
"vivo": {
"category": "IM",
"classification": 1,
"notifyType": 4
},
"meizu": {
"notifyType": 1
},
"googleFCM": {
"channelId": "im_channel",
"image": "https://example.com/image.png",
"priority": "high",
"notificationMode": "notification"
}
}
注意:
示例中所有保留的字段都会生效,请删除不需要的字段(或整个分组),不要原样使用。
保留的字段请将示例值替换为实际值,尤其是通知渠道 channelId、模板 ID 和模板参数、image 图片地址、sound 铃音文件名。
示例中有 SDK 默认值的字段(如各通道的 category、vivo.notifyType、googleFCM.priority),取值与默认值相同,不需要修改时可以直接删除。
在代码中组装 notification 并赋值给 pushInfo,其余发送代码与 V2TIMPushInfo 基础用法 相同。
Android
iOS
Java
Kotlin
import org.json.JSONObject;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> commonConfig = new HashMap<>();
commonConfig.put("image", "https://example.com/image.png");
commonConfig.put("notificationMode", "notification");
commonConfig.put("tencentPushTemplateId", "templateid");
Map<String, Object> tencentPushTemplateParam = new HashMap<>();
tencentPushTemplateParam.put("address", "1908 会议室");
tencentPushTemplateParam.put("time", "3 分钟");
commonConfig.put("tencentPushTemplateParam", tencentPushTemplateParam);

Map<String, Object> androidConfig = new HashMap<>();
androidConfig.put("sound", "private_ring");

Map<String, Object> ios = new HashMap<>();
ios.put("pushType", 0);
ios.put("sound", "default");
ios.put("ignoreBadge", false);
ios.put("interruptionLevel", "active");
ios.put("enableBackgroundNotification", false);
ios.put("image", "https://example.com/image.png");

Map<String, Object> harmony = new HashMap<>();
harmony.put("category", "IM");
harmony.put("image", "https://example.com/image.png");
harmony.put("ignoreBadge", false);
harmony.put("sound", "alert.mp3");
harmony.put("soundDuration", 10);

Map<String, Object> huawei = new HashMap<>();
huawei.put("category", "IM");
huawei.put("image", "https://example.com/image.png");

Map<String, Object> honor = new HashMap<>();
honor.put("importance", "NORMAL");
honor.put("image", "https://example.com/image.png");

Map<String, Object> xiaomiTemplateParam = new HashMap<>();
xiaomiTemplateParam.put("keywords1", "张三");
xiaomiTemplateParam.put("keywords2", "你好,在吗?");
Map<String, Object> xiaomi = new HashMap<>();
xiaomi.put("channelId", "im_channel");
xiaomi.put("templateId", "P10032");
xiaomi.put("templateParam", xiaomiTemplateParam);

Map<String, Object> oppoTemplateTitle = new HashMap<>();
oppoTemplateTitle.put("city", "北京");
Map<String, Object> oppoTemplateContent = new HashMap<>();
oppoTemplateContent.put("userName", "汤姆");
oppoTemplateContent.put("city", "深圳市");
Map<String, Object> oppo = new HashMap<>();
oppo.put("channelId", "im_channel");
oppo.put("category", "IM");
oppo.put("notifyLevel", 2);
oppo.put("templateId", "oppoid");
oppo.put("templateTitle", oppoTemplateTitle);
oppo.put("templateContent", oppoTemplateContent);

Map<String, Object> vivo = new HashMap<>();
vivo.put("category", "IM");
vivo.put("classification", 1);
vivo.put("notifyType", 4);

Map<String, Object> meizu = new HashMap<>();
meizu.put("notifyType", 1);

Map<String, Object> googleFCM = new HashMap<>();
googleFCM.put("channelId", "im_channel");
googleFCM.put("image", "https://example.com/image.png");
googleFCM.put("priority", "high");
googleFCM.put("notificationMode", "notification");

Map<String, Object> notification = new HashMap<>();
notification.put("commonConfig", commonConfig);
notification.put("android", androidConfig);
notification.put("ios", ios);
notification.put("harmony", harmony);
notification.put("huawei", huawei);
notification.put("honor", honor);
notification.put("xiaomi", xiaomi);
notification.put("oppo", oppo);
notification.put("vivo", vivo);
notification.put("meizu", meizu);
notification.put("googleFCM", googleFCM);

pushInfo.setNotification(new JSONObject(notification).toString());
import org.json.JSONObject

val notification = mapOf(
"commonConfig" to mapOf(
"image" to "https://example.com/image.png",
"notificationMode" to "notification",
"tencentPushTemplateId" to "templateid",
"tencentPushTemplateParam" to mapOf("address" to "1908 会议室", "time" to "3 分钟")
),
"android" to mapOf(
"sound" to "private_ring"
),
"ios" to mapOf(
"pushType" to 0,
"sound" to "default",
"ignoreBadge" to false,
"interruptionLevel" to "active",
"enableBackgroundNotification" to false,
"image" to "https://example.com/image.png"
),
"harmony" to mapOf(
"category" to "IM",
"image" to "https://example.com/image.png",
"ignoreBadge" to false,
"sound" to "alert.mp3",
"soundDuration" to 10
),
"huawei" to mapOf(
"category" to "IM",
"image" to "https://example.com/image.png"
),
"honor" to mapOf(
"importance" to "NORMAL",
"image" to "https://example.com/image.png"
),
"xiaomi" to mapOf(
"channelId" to "im_channel",
"templateId" to "P10032",
"templateParam" to mapOf("keywords1" to "张三", "keywords2" to "你好,在吗?")
),
"oppo" to mapOf(
"channelId" to "im_channel",
"category" to "IM",
"notifyLevel" to 2,
"templateId" to "oppoid",
"templateTitle" to mapOf("city" to "北京"),
"templateContent" to mapOf("userName" to "汤姆", "city" to "深圳市")
),
"vivo" to mapOf(
"category" to "IM",
"classification" to 1,
"notifyType" to 4
),
"meizu" to mapOf(
"notifyType" to 1
),
"googleFCM" to mapOf(
"channelId" to "im_channel",
"image" to "https://example.com/image.png",
"priority" to "high",
"notificationMode" to "notification"
)
)

pushInfo.notification = JSONObject(notification).toString()
OC
Swift
NSDictionary *notification = @{
@"commonConfig": @{
@"image": @"https://example.com/image.png",
@"notificationMode": @"notification",
@"tencentPushTemplateId": @"templateid",
@"tencentPushTemplateParam": @{@"address": @"1908 会议室", @"time": @"3 分钟"}
},
@"android": @{
@"sound": @"private_ring"
},
@"ios": @{
@"pushType": @0,
@"sound": @"default",
@"ignoreBadge": @NO,
@"interruptionLevel": @"active",
@"enableBackgroundNotification": @NO,
@"image": @"https://example.com/image.png"
},
@"harmony": @{
@"category": @"IM",
@"image": @"https://example.com/image.png",
@"ignoreBadge": @NO,
@"sound": @"alert.mp3",
@"soundDuration": @10
},
@"huawei": @{
@"category": @"IM",
@"image": @"https://example.com/image.png"
},
@"honor": @{
@"importance": @"NORMAL",
@"image": @"https://example.com/image.png"
},
@"xiaomi": @{
@"channelId": @"im_channel",
@"templateId": @"P10032",
@"templateParam": @{@"keywords1": @"张三", @"keywords2": @"你好,在吗?"}
},
@"oppo": @{
@"channelId": @"im_channel",
@"category": @"IM",
@"notifyLevel": @2,
@"templateId": @"oppoid",
@"templateTitle": @{@"city": @"北京"},
@"templateContent": @{@"userName": @"汤姆", @"city": @"深圳市"}
},
@"vivo": @{
@"category": @"IM",
@"classification": @1,
@"notifyType": @4
},
@"meizu": @{
@"notifyType": @1
},
@"googleFCM": @{
@"channelId": @"im_channel",
@"image": @"https://example.com/image.png",
@"priority": @"high",
@"notificationMode": @"notification"
}
};

NSData *data = [NSJSONSerialization dataWithJSONObject:notification options:0 error:nil];
pushInfo.notification = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
let commonConfig: [String: Any] = [
"image": "https://example.com/image.png",
"notificationMode": "notification",
"tencentPushTemplateId": "templateid",
"tencentPushTemplateParam": ["address": "1908 会议室", "time": "3 分钟"]
]

let androidConfig: [String: Any] = [
"sound": "private_ring"
]

let ios: [String: Any] = [
"pushType": 0,
"sound": "default",
"ignoreBadge": false,
"interruptionLevel": "active",
"enableBackgroundNotification": false,
"image": "https://example.com/image.png"
]

let harmony: [String: Any] = [
"category": "IM",
"image": "https://example.com/image.png",
"ignoreBadge": false,
"sound": "alert.mp3",
"soundDuration": 10
]

let huawei: [String: Any] = [
"category": "IM",
"image": "https://example.com/image.png"
]

let honor: [String: Any] = [
"importance": "NORMAL",
"image": "https://example.com/image.png"
]

let xiaomi: [String: Any] = [
"channelId": "im_channel",
"templateId": "P10032",
"templateParam": ["keywords1": "张三", "keywords2": "你好,在吗?"]
]

let oppo: [String: Any] = [
"channelId": "im_channel",
"category": "IM",
"notifyLevel": 2,
"templateId": "oppoid",
"templateTitle": ["city": "北京"],
"templateContent": ["userName": "汤姆", "city": "深圳市"]
]

let vivo: [String: Any] = [
"category": "IM",
"classification": 1,
"notifyType": 4
]

let meizu: [String: Any] = [
"notifyType": 1
]

let googleFCM: [String: Any] = [
"channelId": "im_channel",
"image": "https://example.com/image.png",
"priority": "high",
"notificationMode": "notification"
]

let notification: [String: Any] = [
"commonConfig": commonConfig,
"android": androidConfig,
"ios": ios,
"harmony": harmony,
"huawei": huawei,
"honor": honor,
"xiaomi": xiaomi,
"oppo": oppo,
"vivo": vivo,
"meizu": meizu,
"googleFCM": googleFCM
]

if let data = try? JSONSerialization.data(withJSONObject: notification) {
pushInfo.notification = String(data: data, encoding: .utf8)
}

notification 字段说明

共 11 个分组。“SDK 默认值”为未填写时 SDK 自动填充的值,“-”表示不填充。
commonConfig
android
ios
harmony
huawei
honor
xiaomi
oppo
vivo
meizu
googleFCM
字段
类型
SDK 默认值
说明
image
String
-
通知图片,URL 必须使用 HTTPS 协议,例如 https://example.com/image.png。
notificationMode
String
-
通知模式:
"notification":通知栏消息;
"data":透传消息,不展示通知栏。
不设置时为通知栏消息。
tencentPushTemplateId
String
-
推送模板 ID,模板在控制台创建并生成。
tencentPushTemplateParam
Object / String
-
推送模板填充参数,key 与模板变量一致。
例:模板为“您参与的会议,地址 {address},将于 {time} 后开始!”,参数为 {"address": "1908 会议室", "time": "3 分钟"}。
字段
类型
SDK 默认值
说明
sound
String
-
自定义铃音,填写 Android 工程 res/raw 目录中的铃音文件名,不带后缀。
仅华为、FCM 通道支持;FCM 在 Android 8.0 及以上需在 googleFCM.channelId 对应的通知渠道中设置铃音。
字段
类型
SDK 默认值
说明
pushType
Integer
0
推送类型:
0:普通 APNs 推送;
1:VoIP 推送。
sound
String
-
铃音:
"default":系统声音;
"push.no_sound":静音;
自定义铃音:先将铃音文件添加到 Xcode 工程,再填写文件名(带后缀)。
ignoreBadge
Boolean
false
true:这条消息不增加 App 图标的未读角标。
interruptionLevel
String
-
通知级别(iOS 15 及以上支持):
"passive":无声音、振动和横幅,只出现在通知中心;
"active":有声音或振动,并显示横幅(系统默认);
"time-sensitive":专注模式下也会提醒,需在苹果开发者平台和 Xcode 工程中开启对应能力;
"critical":静音模式下也会提醒,需向苹果申请。
enableBackgroundNotification
Boolean
false
true:离线接收时唤起应用,并透传 clickPayload。
image
String
-
通知图片,URL 必须使用 HTTPS 协议。支持 JPEG、GIF、PNG,大小不超过 10 MB。
需在 IM 控制台开启 mutable-content,并接入 Notification Service Extension;获取图片的 key 为 "image"。
字段
类型
SDK 默认值
说明
category
String
"IM"
消息类别,详见 华为消息分类。
image
String
-
通知图片,URL 必须使用 HTTPS 协议。支持 png、jpg、jpeg、heif、gif、bmp,图片长 × 宽 < 25000 像素。
ignoreBadge
Boolean
false
true:这条消息不增加 App 图标的未读角标。
sound
String
-
自定义铃音,铃音文件需放在应用的 /resources/rawfile 目录下,填写文件名,例如 "alert.mp3"。支持 MP3、WAV、MPEG 等格式,不设置时使用系统铃音。
未设置 soundDuration 时,铃音建议不超过 30 秒,超过会被截断。
soundDuration
Integer
-
铃音播放时长,单位为秒,取值范围 [1, 60],需同时设置 sound。铃音时长不足时循环播放,到达设定时长后停止。
字段
类型
SDK 默认值
说明
category
String
"IM"
消息分类,详见 华为消息分类。
image
String
-
通知图片,URL 必须使用 HTTPS 协议。图片小于 512 KB,建议规格 40dp × 40dp、弧角 8dp,格式建议 JPG、JPEG、PNG。
字段
类型
SDK 默认值
说明
importance
String
"NORMAL"
消息分类,详见 荣耀消息分类:
"NORMAL":服务通讯类;
"LOW":资讯营销类。
image
String
-
通知图片,URL 必须使用 HTTPS 协议。图片小于 100 KB,建议规格 160px × 160px、弧角 32px。
字段
类型
SDK 默认值
说明
channelId
String
-
通知渠道 ID,Android 8.0 及以上系统使用。
templateId
String
-
私信模板 ID。也可在 IM 控制台配置,配置后无需修改代码。
templateParam
Object / String
-
模板参数:
key 和个数须与模板配置完全一致;
参数值长度 1~128 字符,不能为纯空格;
不支持 emoji、特殊符号(\\p{So})及未分配的 Unicode 字符。
说明:
小米模板 ID 也支持在 IM 控制台设置,常用来适配 IM 场景下(私信消息)推送消息接入推送模板。控制台设置模板 ID 后,会默认填充 V2TIMPushInfo 的 title 和 desc 字段内容给模板标题和内容,等效于:
{
"xiaomi": {
"templateParam": { "keywords1": "title", "keywords2": "desc" }
}
}
对应的申请模板示例(因为小米要求“主标题首位不可以变量开头”,所以示例模板标题前面增加“@”,可根据实际情况自行适配):



只需在控制台填好模板 ID,存量 IM 用户的离线消息就会自动走私信模板通道,不用改代码、不用发版。IM 类型消息也建议统一用这种方式接入私信模板。

字段
类型
SDK 默认值
说明
channelId
String
-
通知渠道 ID,Android 8.0 及以上系统使用。接入 OPPO 推送时必须设置。
category
String
"IM"
消息分类,详见 OPPO 消息分类:
通讯与服务类:"IM"、"ACCOUNT" 等;
内容与营销类:"NEWS"、"CONTENT" 等。
notifyLevel
Integer
-
通知栏提醒等级,category 为 "IM" 时生效:
1:通知栏;
2:通知栏 + 锁屏(OPPO 默认);
16:通知栏 + 锁屏 + 横幅 + 震动 + 铃声。
templateId
String
-
私信模板 ID,申请方式详见 OPPO 私信通道,不支持自拟。也可在 IM 控制台配置,配置后无需修改代码。
templateTitle
Object / String
-
标题模板参数。
例:模板标题为“欢迎来到 ${city}”,参数为 {"city": "北京"}。
templateContent
Object / String
-
内容模板参数。
例:模板内容为“欢迎 ${userName} 来到 ${city}”,参数为 {"userName": "汤姆", "city": "深圳市"}。
说明:
OPPO 模板 ID 也支持在 IM 控制台设置,常用来适配 IM 场景下(category = "IM")推送消息接入推送模板。控制台设置模板 ID 后,会默认填充 V2TIMPushInfo 的 title 和 desc 字段内容给模板标题和内容,等效于:
{
"oppo": {
"templateTitle": { "title": "titleInfo" },
"templateContent": { "desc": "descInfo" }
}
}
对应的申请模板示例:



只需在控制台填好模板 ID,存量 IM 用户的离线消息就会自动走私信模板通道,不用改代码、不用发版。IM 类型消息也建议统一用这种方式接入私信模板。
字段
类型
SDK 默认值
说明
category
String
"IM"
消息类别,详见 vivo 消息分类。
classification
Integer
1
旧版消息分类:0 为运营消息,1 为系统消息。已设置 category 时无需关注。
notifyType
Integer
4
通知类型:
1:无;
2:响铃;
3:振动;
4:响铃和振动。
字段
类型
SDK 默认值
说明
notifyType
Integer
1
消息分类,详见 魅族消息分类:
0:公信消息;
1:私信消息。
字段
类型
SDK 默认值
说明
channelId
String
-
通知渠道 ID,Android 8.0 及以上系统使用。
image
String
-
通知图片,URL 必须使用 HTTPS 协议。图片小于 1 MB;未展开时显示为大图标,展开后显示为大图片。
priority
String
"high"
消息优先级:
"normal":普通优先级,应用在后台时可能延迟送达;
"high":高优先级,设备处于低电耗模式时也会尝试立即送达。
notificationMode
String
"notification"
通知模式,取值同 commonConfig.notificationMode,仅对 FCM 生效,优先级高于 commonConfig.notificationMode。
未设置时与 commonConfig.notificationMode 一致。

V2TIMOfflinePushInfo(全平台可用)

注意:
Android、iOS 上的 V2TIMOfflinePushInfo 及对应的 sendMessage 接口已标记为废弃(编译时有告警),但仍可正常使用。建议 Android、iOS 新接入使用 V2TIMPushInfo。
其他平台请继续使用 V2TIMOfflinePushInfo。
使用此结构时,SDK 不会自动填充 V2TIMPushInfo 基础用法 中的默认配置。

各平台 API 参考

平台
API 文档
Android
iOS
C++
C
HarmonyOS

通用属性说明

属性
类型
含义
是否在通知栏可见
title
String
离线推送通知栏标题。
可见
desc
String
离线推送通知栏正文(自定义消息必填)。
可见
ext
Android:byte[]
iOS:NSString
透传扩展字段,点击推送后 APP 内读取。
不可见
disablePush
boolean
是否关闭本条离线推送。
不可见(true 则整条通知都不出现)
vendorParams
String(JSON)
各厂商扩展参数(fcmPriority、vivoNotifyType、oppoTemplateId 等)。
不可见(但影响展示行为)
其他平台、厂商相关属性(如 iOSSound、AndroidOPPOChannelID 等)请参见 V2TIMOfflinePushInfo 各平台 API 参考。

vendorParams 字段说明

V2TIMOfflinePushInfo.vendorParams 以 JSON 字符串的形式,透传各厂商推送通道的专属高级配置。您可以按需组合以下字段,SDK 会根据最终命中的推送通道自动取用对应参数。
注意:
IMSDK 8.7 及以上版本支持。

字段列表

特性分类
字段
类型
使用说明
备注
FCM 消息优先级
fcmPriority
String
FCM 推送消息优先级设置:
"normal":普通优先级,应用在前台运行时,普通优先级消息会被立即传递。当应用在后台运行时,消息传递可能会延迟。如果是对时间不太敏感的消息(例如新电子邮件通知、使界面保持同步或在后台同步应用数据),建议您选择普通传递优先级;
"high":高优先级,即使设备处于低电耗模式,FCM 也会立即尝试传递高优先级消息。 高优先级消息适用于对时间敏感的用户可见内容。
无
vivo 通知类型
vivoNotifyType
Integer
vivo 通知类型:
1:无。
2:响铃。
3:振动。
4:响铃和振动。
默认值:4。
无
OPPO 私信模板
oppoTemplateId
String
OPPO 私信申请的模板 ID,申请方式详见 OPPO 私信通道:
下发对应私信模板时必须携带,不支持自拟。
说明:
控制台也支持设置模板 ID, 常用来适配 IM 场景下 (category = "IM") 推送消息接入推送模板:
控制台设置模板 ID 后,会默认填充 V2TIMOfflinePushInfo 的 title 和 desc 字段内容给模板标题和内容,格式如下:
{
"oppoTitleParam": {
"title":"titleInfo"
},
"oppoContentParam":{
"desc":"descInfo"
}
}
对应的申请模板示例:

只需在控制台填好模板 ID,存量 IM 用户的离线消息就会自动走私信模板通道,不用改代码、不用发版。IM 类型消息也建议统一用这种方式接入私信模板。
oppoTitleParam
JSON String
OPPO 标题模板填充参数:
例:私信模板 ID 标题模板为:欢迎来到$ {city} $ ,$ {city} $ 欢迎您。
此参数内容为:{“city”:“北京”}
oppoContentParam
JSON String
OPPO 内容模板填充参数:
例:私信模板 ID 对应的内容模板为:欢迎$ {userName} $ 来到$ {city} $
参数内容为:{“userName”:“汤姆”,“city”:“深圳市”}
推送模板
pushTemplateId
String
推送模板 ID。
模板在控制台创建并生成,客户端发送时指定。
无
pushTemplateParam
JSON String
推送模板填充参数。
例:
对应的模板是:
{appName} 发来一条消息
您参与的会议,地址 {address} ,将于 {time} 后开始!
参数内容为:
{
"appName": " TIMPush ",
"address":" 1908 会议室 ",
"time":" 3 分钟 "
}
无
鸿蒙自定义铃音
harmonySound
String
自定义消息通知铃声。
此处设置的铃声文件必须放在应用的 /resources/rawfile 路径下。例如设置为 alert.mp3,对应应用本地的 /resources/rawfile/alert.mp3 文件。支持的文件格式包括 MP3、WAV、MPEG 等,如果不设置,则用默认系统铃声。
当请求不携带 soundDuration 字段时,建议铃声时长不超过 30 秒,若超过 30 秒则截断处理;当请求携带 soundDuration 字段时,详情请参见 soundDuration 字段说明。
无
harmonySoundDuration
Integer
自定义消息通知铃声时长。
需要配合 harmonySound 字段使用,只有当请求同时携带 harmonySound 字段,harmonySoundDuration 字段才会生效。仅支持数字,单位为秒,取值范围 [1, 60]。
harmonySound 字段传入的自定义消息通知铃声会播放至 harmonySoundDuration 字段值后停止,若自定义消息通知铃声对应的时长不足 harmonySoundDuration 字段值则会循环播放,在达到 harmonySoundDuration 字段值后停止。
无
小米推送模板
xiaomiTemplateId
String
消息模板 ID
说明:
控制台也支持设置模板 ID, 常用来适配 IM 场景下 (私信消息) 推送消息接入推送模板:
控制台设置模板 ID 后,会默认填充 V2TIMOfflinePushInfo 的 title 和 desc 字段内容给模板标题和内容,格式如下:
{
"xiaomiTemplateParam": {
"keywords1":"title",
"keywords2":"desc"
}

}
对应的申请模板示例:(因为小米要求 “主标题首位不可以变量开头”,所以示例模板标题前面增加 “@”,可根据实际情况自行适配):

只需在控制台填好模板 ID,存量 IM 用户的离线消息就会自动走私信模板通道,不用改代码、不用发版。IM 类型消息也建议统一用这种方式接入私信模板。
xiaomiTemplateParam
JSON String
模板参数,值为 JSON 字符串。
参数格式与个数须与模板配置完全一致;
参数值长度 1~128 字符,不能为纯空格;
不支持 emoji、特殊符号(\\p{So})及未分配的 Unicode 字符。

vendorParams 用法示例

Android
iOS
C++
Java
Kotlin
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
Map<String, Object> map = new HashMap<>();
map.put("fcmPriority", "high");
map.put("vivoNotifyType", 4);

map.put("oppoTemplateId", "oppoid");
Map<String, Object> oppoTitleMap = new HashMap<>();
oppoTitleMap.put("title", "title");
map.put("oppoTitleParam", new Gson().toJson(oppoTitleMap));
Map<String, Object> oppoContentMap = new HashMap<>();
oppoContentMap.put("desc", "desc");
map.put("oppoContentParam", new Gson().toJson(oppoContentMap));

map.put("pushTemplateId", "templateid");
Map<String, Object> pushTemplateParamMap = new HashMap<>();
pushTemplateParamMap.put("key1", "value1");
map.put("pushTemplateParam", new Gson().toJson(pushTemplateParamMap));

map.put("harmonySound", "ring.mp3");
map.put("harmonySoundDuration", 10);

map.put("xiaomiTemplateId", "xiaomiid");
Map<String, Object> xiaomiTemplateParamMap = new HashMap<>();
xiaomiTemplateParamMap.put("keywords1", "value1");
xiaomiTemplateParamMap.put("keywords2", "value2");
map.put("xiaomiTemplateParam", new Gson().toJson(xiaomiTemplateParamMap));

String param = new Gson().toJson(map);
v2TIMOfflinePushInfo.setVendorParams(param);
val map = mutableMapOf<String, Any>(
"fcmPriority" to "high",
"vivoNotifyType" to 4,
"oppoTemplateId" to "oppoid",
"pushTemplateId" to "templateid",
"harmonySound" to "ring.mp3",
"harmonySoundDuration" to 10,
"xiaomiTemplateId" to "xiaomiid"
)

val oppoTitleMap = mapOf("title" to "title")
map["oppoTitleParam"] = Gson().toJson(oppoTitleMap)

val oppoContentMap = mapOf("desc" to "desc")
map["oppoContentParam"] = Gson().toJson(oppoContentMap)

val pushTemplateMap = mapOf("key1" to "value1")
map["pushTemplateParam"] = Gson().toJson(pushTemplateMap)

val xiaomiTemplateMap = mapOf("keywords1" to "value1", "keywords2" to "value2")
map["xiaomiTemplateParam"] = Gson().toJson(xiaomiTemplateMap)

val param = Gson().toJson(map)
val v2TIMOfflinePushInfo = V2TIMOfflinePushInfo()
v2TIMOfflinePushInfo.vendorParams = param
OC
Swift
NSMutableDictionary *map = [@{
@"fcmPriority": @"high",
@"vivoNotifyType": @4,
@"oppoTemplateId": @"oppoid",
@"pushTemplateId": @"templateid",
@"harmonySound": @"ring.mp3",
@"harmonySoundDuration": @10,
@"xiaomiTemplateId": @"xiaomiid"
} mutableCopy];

NSDictionary *oppoTitleMap = @{@"title": @"title"};
NSData *titleData = [NSJSONSerialization dataWithJSONObject:oppoTitleMap options:0 error:nil];
NSString *oppoTitleJson = [[NSString alloc] initWithData:titleData encoding:NSUTF8StringEncoding];
[map setObject:oppoTitleJson forKey:@"oppoTitleParam"];

NSDictionary *oppoContentMap = @{@"desc": @"desc"};
NSData *contentData = [NSJSONSerialization dataWithJSONObject:oppoContentMap options:0 error:nil];
NSString *oppoContentJson = [[NSString alloc] initWithData:contentData encoding:NSUTF8StringEncoding];
[map setObject:oppoContentJson forKey:@"oppoContentParam"];

NSDictionary *pushTemplateParamMap = @{@"key1": @"value1"};
NSData *pushTemplateData = [NSJSONSerialization dataWithJSONObject:pushTemplateParamMap options:0 error:nil];
NSString *pushTemplateJson = [[NSString alloc] initWithData:pushTemplateData encoding:NSUTF8StringEncoding];
[map setObject:pushTemplateJson forKey:@"pushTemplateParam"];


NSDictionary *xiaomiPushTemplateParamMap = @{@"keywords1": @"value1", @"keywords2": @"value2"};
NSData *xiaomiPushTemplateData = [NSJSONSerialization dataWithJSONObject:xiaomiPushTemplateParamMap options:0 error:nil];
NSString *xiaomiPushTemplateJson = [[NSString alloc] initWithData:xiaomiPushTemplateData encoding:NSUTF8StringEncoding];
[map setObject:xiaomiPushTemplateJson forKey:@"xiaomiTemplateParam"];

NSData *paramsData = [NSJSONSerialization dataWithJSONObject:map options:0 error:nil];
NSString *params = [[NSString alloc] initWithData:paramsData encoding:NSUTF8StringEncoding];

V2TIMOfflinePushInfo *v2TIMOfflinePushInfo = [[V2TIMOfflinePushInfo alloc] init];
v2TIMOfflinePushInfo.vendorParams = params;
var map: [String: Any] = [
"fcmPriority": "high",
"vivoNotifyType": 4,
"oppoTemplateId": "oppoid",
"pushTemplateId": "templateid",
"harmonySound": "ring.mp3",
"harmonySoundDuration": 10,
"xiaomiTemplateId": "xiaomiid"
]

let oppoTitleMap: [String: String] = ["title": "title"]
if let titleData = try? JSONSerialization.data(withJSONObject: oppoTitleMap),
let oppoTitleJson = String(data: titleData, encoding: .utf8) {
map["oppoTitleParam"] = oppoTitleJson
}

let oppoContentMap: [String: String] = ["desc": "desc"]
if let contentData = try? JSONSerialization.data(withJSONObject: oppoContentMap),
let oppoContentJson = String(data: contentData, encoding: .utf8) {
map["oppoContentParam"] = oppoContentJson
}

let pushTemplateParamMap: [String: String] = ["key1": "value1"]
if let pushTemplateData = try? JSONSerialization.data(withJSONObject: pushTemplateParamMap),
let pushTemplateJson = String(data: pushTemplateData, encoding: .utf8) {
map["pushTemplateParam"] = pushTemplateJson
}

let xiaomiTemplateParamMap: [String: String] = ["keywords1": "value1", "keywords2": "value2"]
if let xiaomiTemplateData = try? JSONSerialization.data(withJSONObject: xiaomiTemplateParamMap),
let xiaomiTemplateJson = String(data: xiaomiTemplateData, encoding: .utf8) {
map["xiaomiTemplateParam"] = xiaomiTemplateJson
}

let paramsData = try! JSONSerialization.data(withJSONObject: map)
let params = String(data: paramsData, encoding: .utf8)!

let v2TIMOfflinePushInfo = V2TIMOfflinePushInfo()
v2TIMOfflinePushInfo.vendorParams = params;
#include <sstream>
#include <string>

V2TIMOfflinePushInfo offline_push_info;
//std::string param = R"({"fcmPriority":"high","vivoNotifyType":4})";

std::ostringstream param;
// 拼主结构体
param << "{";
param << "\\"fcmPriority\\":\\"high\\",";
param << "\\"vivoNotifyType\\":4,";
param << "\\"oppoTemplateId\\":\\"oppoid\\",";
param << "\\"pushTemplateId\\":\\"templateid\\",";
param << "\\"harmonySound\\":\\"ring.mp3\\",";
param << "\\"harmonySoundDuration\\":10,";
param << "\\"xiaomiTemplateId\\":\\"xiaomiid\\",";

// 拼oppoTitleParam的json字符串
std::string oppo_title_json = "{\\"title\\":\\"title\\"}";
param << "\\"oppoTitleParam\\":\\"";
for (const char c : oppo_title_json) {
// 转义嵌套json里的双引号
if (c == '"') param << '\\\\';
param << c;
}
param << "\\",";

// 拼oppoContentParam的json字符串
std::string oppo_content_json = "{\\"desc\\":\\"desc\\"}";
param << "\\"oppoContentParam\\":\\"";
for (const char c : oppo_content_json) {
if (c == '"') param << '\\\\';
param << c;
}
param << "\\",";

// 拼pushTemplateParam的json字符串
std::string push_template_json = "{\\"key1\\":\\"value1\\"}";
param << "\\"pushTemplateParam\\":\\"";
for (const char c : push_template_json) {
if (c == '"') param << '\\\\';
param << c;
}
param << "\\",";

// 拼xiaomiTemplateParam的json字符串(新增)
std::string xiaomi_template_json = "{\\"keywords1\\":\\"value1\\",\\"keywords2\\":\\"value2\\"}";
param << "\\"xiaomiTemplateParam\\":\\"";
for (const char c : xiaomi_template_json) {
if (c == '"') param << '\\\\';
param << c;
}
param << "\\"}";
offline_push_info.vendorParams = param.str();

新旧对照

Android、iOS 从 V2TIMOfflinePushInfo 切换到 V2TIMPushInfo 时,可参考以下对照。

发送接口对照

项目
V2TIMOfflinePushInfo(旧)
V2TIMPushInfo(新)
发送接口
sendMessage(message, receiver, groupID, priority, onlineUserOnly, offlinePushInfo, ...)
sendMessage(message, userID, groupID, option, ...)
消息优先级
priority 参数
option.priority
仅在线用户接收
onlineUserOnly 参数
option.onlineUserOnly
推送配置
offlinePushInfo 参数
option.pushInfo
推送配置为空时
正常推送
不推送
关闭本条推送
设置 disablePush 为 true
不设置 option.pushInfo
消息分类等默认配置
不自动填充
SDK 自动填充,详见 V2TIMPushInfo 基础用法

字段对照

“新字段”中的点号表示 notification 中的层级,例如 ios.sound 表示 {"ios": {"sound": "..."}}。
旧字段
新字段
title
title
desc
desc
ext
clickPayload
disablePush
无,不设置 option.pushInfo 即不推送
iOSPushType
ios.pushType
iOSSound
ios.sound
ignoreIOSBadge
ios.ignoreBadge
iOSInterruptionLevel
ios.interruptionLevel
enableIOSBackgroundNotification
ios.enableBackgroundNotification
iOSImage
ios.image
AndroidSound
android.sound
AndroidHuaWeiCategory
huawei.category
AndroidHuaWeiImage
huawei.image
AndroidHonorImportance
honor.importance
AndroidHonorImage
honor.image
AndroidXiaoMiChannelID
xiaomi.channelId
vendorParams.xiaomiTemplateId
xiaomi.templateId
vendorParams.xiaomiTemplateParam
xiaomi.templateParam
AndroidOPPOChannelID
oppo.channelId
AndroidOPPOCategory
oppo.category
AndroidOPPONotifyLevel
oppo.notifyLevel
vendorParams.oppoTemplateId
oppo.templateId
vendorParams.oppoTitleParam
oppo.templateTitle
vendorParams.oppoContentParam
oppo.templateContent
AndroidVIVOCategory
vivo.category
AndroidVIVOClassification
vivo.classification
vendorParams.vivoNotifyType
vivo.notifyType
AndroidMeizuNotifyType
meizu.notifyType
AndroidFCMChannelID
googleFCM.channelId
AndroidFCMImage
googleFCM.image
vendorParams.fcmPriority
googleFCM.priority
HarmonyCategory
harmony.category
HarmonyImage
harmony.image
ignoreHarmonyBadge
harmony.ignoreBadge
vendorParams.harmonySound
harmony.sound
vendorParams.harmonySoundDuration
harmony.soundDuration
vendorParams.pushTemplateId
commonConfig.tencentPushTemplateId
vendorParams.pushTemplateParam
commonConfig.tencentPushTemplateParam
无(新增)
commonConfig.image
无(新增)
commonConfig.notificationMode
无(新增)
googleFCM.notificationMode