自定义铃音

下载
聚焦模式
字号
最后更新时间： 2026-09-21 16:14:32
功能概述
传统提示音缺乏辨识度，影响重要推送效果。腾讯云推送服务提供自定义铃声能力，支持开发者针对不同业务场景（如支付成功、物流更新、活动上新等）配置专属音效，提升消息辨识度与通知打开率。
注意：
离线推送消息铃音不设置，默认跟随设备的系统通知设置，以华为为例，详细参见：手机设置 > 通知 > 应用的通知管理 > 通知铃声。
自定义铃声需要按照厂商平台逐一设置支持，详细参见以下方法总结：不同厂商不同平台自定义铃音方式有区别，Android 8.0 支持厂商还需要通过 channel 来设置，响铃时长和铃音资源时长有关。
通道支持说明
由于不同手机系统的限制，仅部分通道支持自定义铃声功能，支持情况如下：
厂商
是否支持自定义铃音
iOS
支持
FCM
支持
各端功能实现
Android
iOS
Flutter
uni-app
React Native
微信小程序多端框架
Android 8.0 以下系统
注意：
Chat SDK 6.1.2155 及以上版本支持。
1. 定制的铃音资源文件，Android 添加到工程 raw 目录下。
2. 发送消息指定生效自定义铃音。
REST API
SDK API
请参考 REST API 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake" // 不带后缀
        },
        "ApnsInfo": {
            "Sound": "apns.caf",
        }
    }
}   
若集成了 Chat 相关产品，请您发送消息调用接口 setAndroidSound() 和 setIOSSound()。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidSound("铃音名称");
v2TIMOfflinePushInfo.setIOSSound("铃音名称.mp3");
﻿
String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null,
 V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {
@Override
 public void onProgress(int progress) {
﻿
 }
﻿
@Override
 public void onError(int code, String desc) {
﻿
 }
﻿
@Override
 public void onSuccess(V2TIMMessage v2TIMMessage) {
﻿
 }
});
Android 8.0 及以上系统
Google FCM
1.1 1 将定制的铃音资源文件放在工程资源的 raw 目录下，然后通过以下方式创建通知 channel。
// 自定义创建示例
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    NotificationManager nm = (NotificationManager) context.getSystemService(context.NOTIFICATION_SERVICE);
    NotificationChannel notificationChannel =
            new NotificationChannel("channelId", "channelName", NotificationManager.IMPORTANCE_HIGH);
    notificationChannel.enableLights(true);
    notificationChannel.enableVibration(true);
    notificationChannel.setShowBadge(true);
    notificationChannel.setLockscreenVisibility(Notification.VISIBILITY_PUBLIC);
    
    // "android.resource://包名/raw/private_ring"
    notificationChannel.setSound(Uri.parse("sound"), null);
    nm.createNotificationChannel(notificationChannel);
}
2 发送消息指定自定义铃音的 channelID，
REST API
SDK API
请参考 REST API 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "GoogleChannelID": "test_Google_channel_id",
        }
    }
}   
若集成了 Chat 相关产品，详情请参见 setAndroidFCMChannelID。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidFCMChannelID(PrivateConstants.fcmPushChannelId);
﻿
String msgID = V2TIMManager.getMessageManager().sendMessage(v2TIMMessage, isGroup ? null : userID, isGroup ? groupID : null,
 V2TIMMessage.V2TIM_PRIORITY_DEFAULT, false, v2TIMOfflinePushInfo, new V2TIMSendCallback<V2TIMMessage>() {
@Override
 public void onProgress(int progress) {
    TUIChatUtils.callbackOnProgress(callBack, progress);
 }
﻿
@Override
 public void onError(int code, String desc) {
    TUIChatUtils.callbackOnError(callBack, TAG, code, desc);
 }
﻿
@Override
 public void onSuccess(V2TIMMessage v2TIMMessage) {
﻿
 }
});
注意：
FCM 的 GoogleChannelID 字段仅 Chat SDK 7.0.3754 及以上版本支持。
FCM 自定义铃声或者设置 ChannelID 仅支持上传证书。
1. 请在发送消息的时候设置 OfflinePushInfo 的 iOSSound 字段， iOSSound 传语音文件名。
REST API
SDK API
请参考 REST API 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "ApnsInfo": {
            "Sound": "apns.caf"
        }
    }
}   
若集成了 Chat 相关产品，请您发送消息参考：
V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];
pushInfo.title = @"push title";
pushInfo.iOSSound = @"phone_ringing.caf"; // your voice file's name
[[V2TIMManager sharedInstance] sendMessage:msg receiver:receiver groupID:groupID priority:V2TIM_PRIORITY_DEFAULT onlineUserOnly:NO offlinePushInfo:pushInfo progress:nil succ:^{
﻿
} fail:^(int code, NSString *msg) {
﻿
}];
说明：
离线推送声音设置（仅对 iOS 生效）， 当 iOSSound = kIOSOfflinePushNoSound，表示接收时不会播放声音。
当 iOSSound = kIOSOfflinePushDefaultSound，表示接收时播放系统声音。
如果要自定义 iOSSound，需要先把语音文件链接进 Xcode 工程，然后把语音文件名（带后缀名）设置给 iOSSound。
iOS 自定义铃音长度不能超过 30s。
2. 请在发送消息的时候设置 OfflinePushInfo 的 AndroidSound 字段， AndroidSound 传语音文件名。
REST API
SDK API
请参考 REST API 接口，比如 单发推送接口，字段示例如下：
 {
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // 不带后缀
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
            "OPPOChannelID": "test_OPPO_channel_id",
            "GoogleChannelID": "test_Google_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.caf"
        }
    }
}   
若集成了 Chat 相关产品，请您发送消息参考：
V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];
pushInfo.title = @"push title";
pushInfo.AndroidSound = @"phone_ringing"; // your voice file's name
[[V2TIMManager sharedInstance] sendMessage:msg receiver:receiver groupID:groupID priority:V2TIM_PRIORITY_DEFAULT onlineUserOnly:NO offlinePushInfo:pushInfo progress:nil succ:^{
﻿
} fail:^(int code, NSString *msg) {
﻿
}];
说明：
离线推送声音设置（仅对 Android 生效, 仅 imsdk 6.1 及以上版本支持） 只有谷歌手机支持设置铃音提示。
如果要自定义 AndroidSound，需要先把语音文件放到 Android 工程的 raw 目录中，然后把语音文件名（不需要后缀名）设置给 AndroidSound。
定制的铃音资源文件，Android 添加到工程 raw 目录下，iOS 链接进 Xcode 工程。
请在发送消息的时候设置 offlinePushInfo 的 iOSSound 及 androidSound 字段。
REST API
SDK API
请参考 REST API 接口，例如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // 不带后缀
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
            "OPPOChannelID": "test_OPPO_channel_id",
            "GoogleChannelID": "test_Google_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.caf"
        }
    }
}   
若集成了 Chat 相关产品，请在调用 sendMessage 发送消息的时候设置 offlinePushInfo 的 iOSSound 及 androidSound 字段。
具体各厂商配置，请参阅 Android 及 iOS 模块的内容。调用的方法均在 Flutter 版本的 Chat SDK 中有同名方法。
说明：
接收端需集成 uni-app 腾讯云推送服务（Push）。
发送端 @tencentcloud/chat  ≥ 3.3.2 。
支持 FCM 和 APNS。
接收端
Android
iOS
定制的铃音资源文件，添加到项目 nativeResources/android/res/raw 目录下，如下图所示：
﻿
设置私信通道和自定义铃音
说明：
uni-app 腾讯云推送服务（Push） ≥ 0.5.0。
FCM 使用自定义铃音需要先设置私信通道和自定义铃音。
完成上述步骤后，您可以调用 push.createNotificationChannel 设置 FCM 私信通道和自定义铃音。
在 App.vue 中设置 FCM 私信通道。如图所示:
import * as Push from '@/uni_modules/TencentCloud-Push';
Push.createNotificationChannel({
    channelID: '', // 自定义 channel 的 ID。OPPO 为控制台配置的 channelID
    channelName: '自定义channel',// 自定义channel 名称
    channelDesc: '这只是描述', // 自定义 channel 描述
    channelSound: 'private_ring'  // 自定义铃音的名称且不需要后缀名
}, () => {
    console.log('Push | createNotificationChannel ok');
})
说明：
iOS 自定义铃音，uni-app 必须为正式包。
iOS 自定义铃音长度不能超过 30s。
定制的铃音资源文件，添加到项目 nativeResources/ios/Resources 目录下，如下图所示：
﻿
发送端
1. 升级 @tencentcloud/chat 到最新版本。
npm install @tencentcloud/chat@latest
web
uni-app
小程序
在浏览器控制台查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat  ≥ 3.3.2 如图所示：
﻿
在 HBuilder 日志中查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat  ≥ 3.3.2 如图所示：
﻿
在小程序开发者工具控制台查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat  ≥ 3.3.2 如图所示：
﻿
2. 发送消息，设置 offlinePushInfo 自定义铃音的相关参数。
说明：
谷歌手机 FCM 推送在 Android 8.0 及以上系统设置声音提示，必须设置 androidInfo.FCMChannelID。
含 UI 集成
无 UI 集成
CallKit 集成
说明：
当 apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
当 apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
在 UIKit 中使用 TUIChatService 发送消息时，设置 offlinePushInfo 相关参数，如发送普通文本消息，代码如下：
// 发送普通文本消息
let promise = TUIChatService.sendTextMessage(
{ 
   payload: {   text: 'Hello world!' }
},
{
  // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容
   offlinePushInfo: {
     androidInfo: { // Android 推送配置
        sound: 'private_ring.mp3', // Android 自定义铃音
        FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。
      },
      apnsInfo: { // APNs 推送配置
     // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
     // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
        sound: 'private_ring.caf', // iOS 自定义铃音
      }
   }
}
);
promise.catch((error) => { 
    // 调用异常时业务侧可以通过 promise.catch 捕获异常进行错误处理
});
说明：
当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
在 chat 发送消息时，设置 offlinePushInfo 相关字段，代码如下:
// 消息发送选项
chat.sendMessage(message, {
  // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容
   offlinePushInfo: {
     androidInfo: { // Android 推送配置
        sound: 'private_ring.mp3', // Android 自定义铃音
        XiaoMiChannelID: '', // 小米手机在 Android 8.0 及以上版本必须设置 XiaoMiChannelID
        FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。
        OPPOChannelID: '', // OPPO手机必须设置 OPPOChannelID
      },
      apnsInfo: { // APNs 推送配置
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
        sound: 'private_ring.caf', // iOS 自定义铃音
      }
   }
});
参考文档：Chat SDK - sendMessage 文档﻿
说明：
androidSound 为铃声文件名，不需要后缀名。
iOSSound 为铃声文件名，需要后缀名。
const TUICallKit = uni.requireNativePlugin('TencentCloud-TUICallKit');
const options = { 
  userID: '',
  callMediaType: 1, // 语音通话(callMediaType = 1)、视频通话(callMediaType = 2)
  callParams: {
    // 如果接收方不在线，进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容
    offlinePushInfo: {
      title: 'test-title',
      description: 'you have a test call',
      androidSound: 'private_ring', // Android 离线推送的自定义铃音
      iOSSound: 'private_ring.caf', // iOS 离线推送的自定义铃音
    },
  },
};
TUICallKit.call(options, (res) => {
  if (res.code === 0) {
    console.log('call success');
  } else {
    console.log(`call failed, error message = ${res.msg}`);
  }
});
说明：
接收端需集成 @tencentcloud/react-native-push。
发送端 @tencentcloud/chat  ≥ 3.3.2 。
接收端
Android
iOS
定制的铃音资源文件，添加到项目 MyReactNativeApp/android/app/src/main/res/raw 目录下，如果该目录不存在，请手动创建。如下图所示：
﻿
﻿
﻿
说明：
iOS 自定义铃音长度不能超过 30s。
定制的铃音资源文件，添加项目到 MyReactNativeApp/ios/MyReactNativeApp/Resources 目录下，并用 Xcode 打开 MyReactNativeApp 项目，右键点击项目 > Add Files to "MyReactNativeApp"，将铃音文件添加到工程。如下图所示：
项目
Xcode
﻿
﻿
﻿
﻿
﻿
﻿
发送端
发送消息，设置 offlinePushInfo 自定义铃音的相关参数。
说明：
当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
// 消息发送选项
chat.sendMessage(message, {
  // 如果接收方不在线，则消息将存入漫游，且进行离线推送（在接收方 App 退后台或者进程被 kill 的情况下）。接入侧可自定义离线推送的标题及内容
   offlinePushInfo: {
     androidInfo: { // Android 推送配置
        sound: 'private_ring.mp3', // Android 自定义铃音
        FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。
      },
      apnsInfo: { // APNs 推送配置
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
        sound: 'private_ring.caf', // iOS 自定义铃音
      }
   }
});
参考文档：Chat SDK > sendMessage 文档﻿
客户端配置
Android
iOS
说明：
配置原生资源请参考文档。
1、添加自定义铃音文件
把铃音文件添加到项目 miniapp/android/nativeResources/res/raw 目录下，如下图所示：
﻿
﻿
﻿
2、创建客户端通知 channel
在 App 启动时调用 Push.createNotificationChannel 方法设置通知 channel。
import Push from "@tencentcloud/donut-push"
﻿
App({
  onLaunch: function () {
    Push.createNotificationChannel({
          channelID: "",  // 自定义 channel 的 ID。
          channelName: "",  // 自定义channel 名称
          channelDesc: "",  // 自定义 channel 描述
          channelSound: ""  // 自定义铃音文件的名称且不需要文件扩展名
        }).then((ret) => {
          console.info("createNotificationChannel success", ret);
        }).catch((ret) => {
          console.error("createNotificationChannel failed", ret);
        });
    }
})
说明：
iOS 自定义铃音长度不能超过 30s。
微信开发者工具版本号 >= 1.06.2412042 。
1、添加自定义铃音文件
把铃音文件添加到项目目录下，如下图所示：
﻿
﻿
﻿
2、可通过构建检查您的 IPA 内是否包含此铃声，注意铃声长度不能超过30秒
﻿
﻿
﻿
服务端 REST API
请求包示例
{
  "From_Account": "administrator",
  "To_Account": ["100480"], 
  "MsgRandom": 3674128,
  "OfflinePushInfo": {
      "PushFlag": 0, 
      "Title": "离线推送标题1adad1",
      "Desc": "离线推送内容11adasd1",
      "Ext":"{\\"aa\\":12123}",
      "AndroidInfo": {
           "Sound": "private_ring123",  // 跟客户端创建的 channel 中的铃声文件名称一致
           "GoogleChannelID": "test_google_channel_id"
       },
       "ApnsInfo": {
            "Sound": "01.caf"// 跟接收端 ipa 包内的铃声文件名称一致
       }
    }
}
﻿
帮助和支持

本页内容是否解决了您的问题？
您也可以联系销售或提交工单以寻求帮助。
填写满意度调查问卷，共创更好文档体验。
文档反馈
tencent cloud

即时通信 IM

自定义铃音

功能概述

通道支持说明

各端功能实现

Android 8.0 以下系统

Android 8.0 及以上系统

Google FCM

接收端

设置私信通道和自定义铃音

发送端

1. 升级 @tencentcloud/chat 到最新版本。

2. 发送消息，设置 offlinePushInfo 自定义铃音的相关参数。

接收端

发送端

客户端配置

1、添加自定义铃音文件

2、创建客户端通知 channel

1、添加自定义铃音文件

2、可通过构建检查您的 IPA 内是否包含此铃声，注意铃声长度不能超过30秒

服务端 REST API

请求包示例

帮助和支持

tencent cloud

即时通信 IM

自定义铃音

功能概述

通道支持说明

各端功能实现

Android 8.0 以下系统

Android 8.0 及以上系统

Google FCM

接收端

设置私信通道和自定义铃音

发送端

1. 升级 @tencentcloud/chat 到最新版本。

2. 发送消息，设置 offlinePushInfo 自定义铃音的相关参数。

接收端

发送端

客户端配置

1、添加自定义铃音文件

﻿﻿﻿

2、创建客户端通知 channel

1、添加自定义铃音文件

2、可通过构建检查您的 IPA 内是否包含此铃声，注意铃声长度不能超过30秒

﻿﻿﻿

服务端 REST API

请求包示例

帮助和支持
