即时通信 IM 自定义铃音

注意：
1. 离线推送消息铃音不设置，默认跟随设备的系统通知设置，以华为为例，详细参见：“手机设置 > 通知 > 应用的通知管理 > 通知铃声”。
2. 自定义铃声需要按照厂商平台逐一设置支持，详细参见以下方法总结：不同厂商不同平台自定义铃音方式有区别，Android 8.0 支持厂商还需要通过 channel 来设置，响铃时长和铃音资源时长有关。
Android
iOS
Flutter
uni-app
React Native
微信小程序多端框架
Android 8.0 以下系统
1. 定制的铃音资源文件，Android 添加到工程 raw 目录下，iOS 链接进 Xcode 工程。
2. 发送消息指定生效自定义铃音。
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // 不带后缀
        },
        "ApnsInfo": {
            "Sound": "apns.mp3",
        }
    }
}   
若集成了 IM 相关产品，请您发送消息调用接口 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) {
﻿
 }
});
注意：
IMSDK  6.1.2155  及以上版本支持。
接口支持华为、小米、FCM 和 APNS。
Android 8.0 及以上系统
华为 和 ANPS
    华为、APNS 可调用上面接口来设置离线推送铃音提示。
OPPO
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. 使用创建的 channel。
﻿创建私信通道。
发送消息指定 channelID 生效自定义铃音，接口设置参考如下，控制台设置见证书的 channelID 字段，两者设置一个即可。
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "OPPOChannelID": "test_OPPO_channel_id",
        }
    }
}   
若集成了 IM 相关产品，请您发送消息调用接口 setAndroidOPPOChannelID。
小米
1. 登录厂商控制台 创建 channel 和配置，其中铃音文件需要添加到您本地 Android Studio 工程的 raw 目录下。
﻿
2. 发送消息指定 channelID 生效自定义铃音，接口设置参考如下，控制台设置见证书的 channelID 字段，两者设置一个即可。
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
        }
    }
}   
若集成了 IM 相关产品，详情请参见 setAndroidXiaoMiChannelID。
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidXiaoMiChannelID("厂商申请的 channel ID");
﻿
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
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，
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "GoogleChannelID": "test_Google_channel_id",
        }
    }
}   
若集成了 IM 相关产品，详情请参见 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) {
﻿
 }
});
注意：
IMSDK 7.0.3754 及以上版本支持。
FCM 自定义铃声或者设置 ChannnelID 仅支持证书模式。
﻿
1. 请在发送消息的时候设置 OfflinePushInfo 的 iOSSound 字段， iOSSound 传语音文件名。
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "ApnsInfo": {
            "Sound": "apns.mp3",
        }
    }
}   
若集成了 IM 相关产品，请您发送消息参考：
V2TIMOfflinePushInfo *pushInfo = [[V2TIMOfflinePushInfo alloc] init];
pushInfo.title = @"push title";
pushInfo.iOSSound = @"phone_ringing.mp3"; // 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 传语音文件名。
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // 不带后缀
            "OPPOChannelID": "test_OPPO_channel_id",
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
            "OPPOChannelID": "test_OPPO_channel_id",
            "GoogleChannelID": "test_Google_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.mp3"
        }
    }
}   
若集成了 IM 相关产品，请您发送消息参考：
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 及以上版本支持） 只有华为和谷歌手机支持设置铃音提示。
小米铃音设置请您参见：服务端 Java SDK 文档。
如果要自定义 AndroidSound，需要先把语音文件放到 Android 工程的 raw 目录中，然后把语音文件名（不需要后缀名）设置给 AndroidSound。
注意：
接口支持华为、小米、FCM 和 APNS。
定制的铃音资源文件，Android 添加到工程 raw 目录下，iOS 链接进 Xcode 工程。
请在发送消息的时候设置 offlinePushInfo 的 iOSSound 及 androidSound 字段。
restAPI
SDK API
请参考 restAPI 接口，比如 单发推送接口，字段示例如下：
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // 不带后缀
            "OPPOChannelID": "test_OPPO_channel_id",
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
            "OPPOChannelID": "test_OPPO_channel_id",
            "GoogleChannelID": "test_Google_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.mp3"
        }
    }
}   
若集成了 IM 相关产品，请在调用 sendMessage 发送消息的时候设置 offlinePushInfo 的 iOSSound 及 androidSound 字段。
具体各厂商配置，请参阅 Android 及 iOS 模块的内容。调用的方法均在 Flutter 版本的 IM SDK 中有同名方法。
说明：
接收端需集成 uni-app 腾讯云推送服务（Push）。
发送端 @tencentcloud/chat  ≥ 3.3.2 。
支持华为、小米、OPPO、FCM 和 APNS。
接收端
Android
iOS
定制的铃音资源文件，添加到项目 nativeResources/android/res/raw 目录下，如下图所示：
﻿
设置私信通道和自定义铃音（ OPPO、FCM 需要设置）
说明：
1. uni-app 腾讯云推送服务（Push） ≥ 0.5.0。
2. OPPO、FCM 使用自定义铃音需要先设置私信通道和自定义铃音。
完上述步骤后，您可以调用 push.createNotificationChannel 设置 OPPO 、FCM 私信通道和自定义铃音。
在 App.vue 中设置 OPPO、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 自定义铃音，uniapp 必须为正式包。
iOS 自定义铃音长度不能超过 30s。
定制的铃音资源文件，添加到项目 nativeResources/ios/Resources 目录下，如下图所示：
﻿
发送端
1. 升级 @tencentcloud/chat 到最新版本。
npm install @tencentcloud/chat@latest
web
uniapp
小程序
在浏览器控制台查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat  ≥ 3.3.2 如图所示：
﻿
在 HBuilder 日志中查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat  ≥ 3.3.2 如图所示：
﻿
在小程序开发者工具控制台查看 TencentCloudChat.VERSION 版本号，来确认 @tencentcloud/chat  ≥ 3.3.2 如图所示：
﻿
2. 发送消息，设置 offlinePushInfo 自定义铃音的相关参数。
说明：
小米手机在 Android 8.0 及以上版本必须设置 androidInfo.XiaoMiChannelID，请您参见：小米自定义铃声。
谷歌手机 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', // Andorid 自定义铃音
        XiaoMiChannelID: '', // 小米手机在 Android 8.0 及以上版本必须设置 XiaoMiChannelID
        FCMChannelID: '', // 谷歌手机 FCM 在 Android 8.0 及以上系统设置声音提示，必须设置 FCMChannelID。
        OPPOChannelID: '', // OPPO手机必须设置 OPPOChannelID
      },
      apnsInfo: { // APNs 推送配置
     // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。
     // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。
        sound: 'private_ring.mp3', // iOS 自定义铃音
      }
   }
}
);
promise.catch((error) => { 
    // 调用异常时业务侧可以通过 promise.catch 捕获异常进行错误处理
});
参考文档：
﻿uikit - TUIChatService 发送消息相关文档﻿
说明：
当 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', // Andorid 自定义铃音
        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.mp3', // 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', // Andorid 离线推送的自定义铃音
      iOSSound: 'private_ring.mp3', // iOS 离线推送的自定义铃音
    },
  },
};
TUICallKit.call(options, (res) => {
  if (res.code === 0) {
    console.log('call success');
  } else {
    console.log(`call failed, error message = ${res.msg}`);
  }
});
参考文档：CallKit 配置 offlinePushInfo﻿
说明：
接收端需集成@tencentcloud/react-native-push。
发送端 @tencentcloud/chat  ≥ 3.3.2 。
支持华为、小米和 APNS。
接收端
Android
iOS
定制的铃音资源文件，添加到项目 MyReactNativeApp/android/app/src/main/res/raw 目录下，如果该目录不存在，请手动创建。如下图所示：
﻿
﻿
﻿
说明：
iOS 自定义铃音长度不能超过 30s。
定制的铃音资源文件，添加到项目到 MyReactNativeApp/ios/MyReactNativeApp/Resources 目录下，并用 XCode 打开 MyReactNativeApp 项目，右键点击项目 > Add Files to "MyReactNativeApp"，将铃音文件添加到工程。如下图所示：
项目
Xcode
﻿
﻿
﻿
﻿
﻿
﻿
发送端
发送消息，设置 offlinePushInfo 自定义铃音的相关参数。
说明：
小米手机在 Android 8.0 及以上版本必须设置 androidInfo.XiaoMiChannelID，请您参见：小米自定义铃声。
当 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', // Andorid 自定义铃音
        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.mp3', // 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 中的铃声文件名称一致
           "OPPOChannelID": "test_oppo_channel_id",
           "XiaoMiChannelID": "test_xiaomi_channel_id",
           "GoogleChannelID": "test_google_channel_id"
       },
       "ApnsInfo": {
            "Sound": "01.caf"// 跟接收端 ipa 包内的铃声文件名称一致
       }
    }
}
常见问题
配置完成后，收到推送但是手机没有铃声？
请先检查是否开启手机系统铃声，再检查 App 的通知权限中是否打开铃声开关。
部分手机离线推送自定义铃音设置无效？
目前支持离线推送自定义铃音的厂商有：华为、OPPO、小米、FCM、APNS。
﻿
自定义铃音

Android 8.0 以下系统

Android 8.0 及以上系统

华为 和 ANPS

OPPO

小米

FCM

接收端

设置私信通道和自定义铃音（ OPPO、FCM 需要设置）

发送端

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

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

接收端

发送端

客户端配置

1、添加自定义铃音文件

﻿﻿﻿

2、创建客户端通知 channel

1、添加自定义铃音文件

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

﻿﻿﻿

服务端 REST API

请求包示例

常见问题

配置完成后，收到推送但是手机没有铃声？

部分手机离线推送自定义铃音设置无效？

华为和 ANPS
