Custom Definition Ringtone

Feature overview
Traditional notification sounds are difficult to distinguish, which can reduce the effectiveness of important push notifications. Tencent Cloud Push provides custom ringtone capabilities, allowing developers to configure dedicated sounds for different business scenarios, such as successful payments, logistics updates, and new promotions. This improves message recognition and notification open rates.
Note:
If no ringtone is configured for offline push notifications, the device's system notification settings are used by default. For example, on Huawei devices, go to Settings > Notifications > Notification management for the app > Notification sound.
Custom ringtones must be configured separately for each supported vendor platform. For details, see the methods summarized below. The configuration method varies by vendor and platform. On Android 8.0 and later, supported vendors also require a notification channel. The playback duration depends on the duration of the sound resource.
Channel support
Due to restrictions imposed by different mobile operating systems, only some channels support custom ringtones, as shown below:
Vendor
Custom ringtone support
iOS
Supported
FCM
Supported
Platform-specific implementation
Android
iOS
Flutter
uni-app
React Native
WeChat Mini Program multi-platform framework
Earlier than Android 8.0
Note:
Supported in Chat SDK version 6.1.2155 and above.
1. Add the custom ringtone resource file to the raw directory of the Android project or link it to the Xcode project for iOS.
2. Specify the custom ringtone when sending a message.
REST API
SDK API
For details, see a REST API such as Single Push. Example fields are as follows:
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake" // Without the filename extension
        },
        "ApnsInfo": {
            "Sound": "apns.caf",
        }
    }
}   
If a Chat product is integrated, call setAndroidSound() and setIOSSound() when sending the message.
V2TIMOfflinePushInfo v2TIMOfflinePushInfo = new V2TIMOfflinePushInfo();
v2TIMOfflinePushInfo.setAndroidSound("ringtone_name");
v2TIMOfflinePushInfo.setIOSSound("ringtone_name.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 or later
FCM
1.1 Place the custom ringtone resource file in the raw directory of the project resources, and then create a notification channel as follows.
// Custom channel creation example
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://package_name/raw/private_ring"
    notificationChannel.setSound(Uri.parse("sound"), null);
    nm.createNotificationChannel(notificationChannel);
}
1.2 Specify the custom ringtone's channelID when sending a message.
REST API
SDK API
For details, see a REST API such as Single Push. Example fields are as follows:
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "GoogleChannelID": "test_Google_channel_id",
        }
    }
}   
If a Chat product is integrated, see setAndroidFCMChannelID for details.
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) {
﻿
 }
});
Note:
The GoogleChannelID field for FCM is supported only in Chat SDK 7.0.3754 or later.
FCM custom ringtones and ChannelID configuration are supported only in certificate mode.
1. When sending a message, set the iOSSound field in OfflinePushInfo to the name of the sound file.
REST API
SDK API
For details, see a REST API such as Single Push. Example fields are as follows:
 {
    // ...
    "OfflinePushInfo": {
        "ApnsInfo": {
            "Sound": "apns.caf"
        }
    }
}   
If a Chat product is integrated, use the following example when sending a message:
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) {
﻿
}];
Note:
The offline push sound setting applies only to iOS. If iOSSound = kIOSOfflinePushNoSound, no sound is played when the notification is received.
If iOSSound = kIOSOfflinePushDefaultSound, the system sound is played when the notification is received.
To customize iOSSound, first link the sound file to the Xcode project, and then set iOSSound to the sound filename, including its filename extension.
An iOS custom ringtone cannot exceed 30 seconds.
2. When sending a message, set the AndroidSound field in OfflinePushInfo to the name of the sound file.
REST API
SDK API
For details, see a REST API such as Single Push. Example fields are as follows:
 {
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // Without the filename extension
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
            "OPPOChannelID": "test_OPPO_channel_id",
            "GoogleChannelID": "test_Google_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.caf"
        }
    }
}   
If a Chat product is integrated, use the following example when sending a message:
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) {
﻿
}];
Note:
The offline push sound setting applies only to Android and requires Chat SDK 6.1 or later. Only Huawei and Google devices support custom notification sounds.
To use a custom AndroidSound, place the audio file in the raw directory of your Android project, and set AndroidSound to the file name (without the extension).
Add the custom ringtone resource file to the raw directory of the Android project or link it to the Xcode project for iOS.
When sending a message, set the iOSSound and androidSound fields in offlinePushInfo.
REST API
SDK API
For details, see a REST API such as Single Push. Example fields are as follows:
 {
    // ...
    "OfflinePushInfo": {
        "AndroidInfo": { 
            "Sound": "shake",  // Without the filename extension
            "XiaoMiChannelID": "test_XiaoMi_channel_id",
            "OPPOChannelID": "test_OPPO_channel_id",
            "GoogleChannelID": "test_Google_channel_id"
        },
        "ApnsInfo": {
            "Sound": "apns.caf"
        }
    }
}   
If a Chat product is integrated, set the iOSSound and androidSound fields in offlinePushInfo when calling sendMessage.
For vendor-specific configuration, see the Android and iOS sections. The Flutter Chat SDK provides methods with the same names.
Note:
The receiving client must integrate Tencent Cloud Push for uni-app.
The sending client requires @tencentcloud/chat 3.3.2 or later.
Huawei, Xiaomi, OPPO, FCM, and APNs are supported.
Receiving client
Android
iOS
Add the custom ringtone resource file to the project's nativeResources/android/res/raw directory, as shown below:
﻿
Configuring a private message channel and custom ringtone (required for OPPO and FCM)
Note:
uni-app Tencent Cloud Push (Push) ≥ 0.5.0.
To use a custom ringtone with OPPO or FCM, first configure a private message channel and custom ringtone.
After completing the preceding steps, call push.createNotificationChannel to configure the OPPO and FCM private message channels and custom ringtone.
Configure the OPPO and FCM private message channels in App.vue, as shown below:
import * as Push from '@/uni_modules/TencentCloud-Push';
Push.createNotificationChannel({
    channelID: '', // ID of the custom channel. For OPPO, use the channelID configured in the console.
    channelName: 'custom channel', // Name of the custom channel
    channelDesc: 'This is a description', // Description of the custom channel
    channelSound: 'private_ring'  // Name of the custom ringtone, without the filename extension
}, () => {
    console.log('Push | createNotificationChannel ok');
})
Note:
To use a custom ringtone on iOS, the uni-app must be a production build.
An iOS custom ringtone cannot exceed 30 seconds.
Add the custom ringtone resource file to the project's nativeResources/ios/Resources directory, as shown below:
﻿
Sending client
1. Upgrade @tencentcloud/chat to the latest version
npm install @tencentcloud/chat@latest
web
uni-app
Mini Program
Check the TencentCloudChat.VERSION value in the browser console to confirm that @tencentcloud/chat is 3.3.2 or later, as shown below:
﻿
Check the TencentCloudChat.VERSION value in the HBuilder logs to confirm that @tencentcloud/chat is 3.3.2 or later, as shown below:
﻿
Check the TencentCloudChat.VERSION value in the Mini Program Developer Tools console to confirm that @tencentcloud/chat is 3.3.2 or later, as shown below:
﻿
2. Send a message and configure custom ringtone parameters in offlinePushInfo
Note:
To configure notification sounds for FCM push on Google devices running Android 8.0 or later, you must set androidInfo.FCMChannelID.
Integration with UI
Integration without UI
CallKit integration
Note:
If apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_NO_SOUND, no sound is played when the notification is received.
If apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND, the system sound is played when the notification is received.
When using TUIChatService in UIKit to send a message, configure the relevant offlinePushInfo parameters. The following example sends a text message:
// Send a text message
let promise = TUIChatService.sendTextMessage(
{ 
   payload: {   text: 'Hello world!' }
},
{
  // If the recipient is offline, the message is stored for roaming and an offline push notification is sent when the recipient's app is in the background or its process has been killed. You can customize the title and content of the offline push notification.
   offlinePushInfo: {
     androidInfo: { // Android push configuration
        sound: 'private_ring.mp3', // Android custom ringtone
        XiaoMiChannelID: '', // Required on Xiaomi devices running Android 8.0 or later
        FCMChannelID: '', // Required to configure notification sounds for FCM on Google devices running Android 8.0 or later
        OPPOChannelID: '', // Required on OPPO devices
      },
      apnsInfo: { // APNs push configuration
     // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_NO_SOUND: no sound is played when the notification is received.
     // apnsInfo.sound = TUIChatEngine.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND: the system sound is played when the notification is received.
        sound: 'private_ring.caf', // iOS custom ringtone
      }
   }
}
);
promise.catch((error) => { 
    // If an exception occurs, catch it with promise.catch for error handling.
});
Note:
If apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND, no sound is played when the notification is received.
If apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND, the system sound is played when the notification is received.
When using Chat to send a message, configure the relevant offlinePushInfo fields as follows:
// Message sending options
chat.sendMessage(message, {
  // If the recipient is offline, the message is stored for roaming and an offline push notification is sent when the recipient's app is in the background or its process has been killed. You can customize the title and content of the offline push notification.
   offlinePushInfo: {
     androidInfo: { // Android push configuration
        sound: 'private_ring.mp3', // Android custom ringtone
        XiaoMiChannelID: '', // Required on Xiaomi devices running Android 8.0 or later
        FCMChannelID: '', // Required to configure notification sounds for FCM on Google devices running Android 8.0 or later
        OPPOChannelID: '', // Required on OPPO devices
      },
      apnsInfo: { // APNs push configuration
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND: no sound is played when the notification is received.
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND: the system sound is played when the notification is received.
        sound: 'private_ring.caf', // iOS custom ringtone
      }
   }
});
Reference: Chat SDK - sendMessage﻿
Note:
androidSound is the ringtone filename without the filename extension.
iOSSound is the ringtone filename with the filename extension.
const TUICallKit = uni.requireNativePlugin('TencentCloud-TUICallKit');
const options = { 
  userID: '',
  callMediaType: 1, // Audio call (callMediaType = 1) or video call (callMediaType = 2)
  callParams: {
    // If the recipient is offline, an offline push notification is sent when the recipient's app is in the background or its process has been killed. You can customize the title and content of the offline push notification.
    offlinePushInfo: {
      title: 'test-title',
      description: 'you have a test call',
      androidSound: 'private_ring', // Custom ringtone for Android offline push
      iOSSound: 'private_ring.caf', // Custom ringtone for iOS offline push
    },
  },
};
TUICallKit.call(options, (res) => {
  if (res.code === 0) {
    console.log('call success');
  } else {
    console.log(`call failed, error message = ${res.msg}`);
  }
});
Note:
The receiving client must integrate @tencentcloud/react-native-push.
The sender requires @tencentcloud/chat ≥ 3.3.2.
Receiving client
Android
iOS
Add the custom ringtone resource file to the MyReactNativeApp/android/app/src/main/res/raw directory. If the directory does not exist, create it manually, as shown below:
﻿
﻿
﻿
Note:
An iOS custom ringtone cannot exceed 30 seconds.
Add the custom ringtone resource file to the MyReactNativeApp/ios/MyReactNativeApp/Resources directory. Open the MyReactNativeApp project in Xcode, right-click the project, choose Add Files to "MyReactNativeApp", and add the ringtone file to the project, as shown below:
Project
Xcode
﻿
﻿
﻿
﻿
﻿
﻿
Sending client
Send a message and configure the custom ringtone parameters in offlinePushInfo.
Note:
If apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND, no sound is played when the notification is received.
If apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND, the system sound is played when the notification is received.
// Message sending options
chat.sendMessage(message, {
  // If the recipient is offline, the message is stored for roaming and an offline push notification is sent when the recipient's app is in the background or its process has been killed. You can customize the title and content of the offline push notification.
   offlinePushInfo: {
     androidInfo: { // Android push configuration
        sound: 'private_ring.mp3', // Android custom ringtone
        XiaoMiChannelID: '', // Required on Xiaomi devices running Android 8.0 or later
        FCMChannelID: '', // Required to configure notification sounds for FCM on Google devices running Android 8.0 or later
        OPPOChannelID: '', // Required on OPPO devices
      },
      apnsInfo: { // APNs push configuration
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND: no sound is played when the notification is received.
     // apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND: the system sound is played when the notification is received.
        sound: 'private_ring.caf', // iOS custom ringtone
      }
   }
});
Reference: Chat SDK > sendMessage﻿
Client configuration
Android
iOS
Note:
For details on configuring native resources, see the documentation.
1. Add the custom ringtone file
Add the ringtone file to the project's miniapp/android/nativeResources/res/raw directory, as shown below:
﻿
﻿
﻿
2. Create a client notification channel
When the app starts, call Push.createNotificationChannel to configure the notification channel.
import Push from "@tencentcloud/donut-push"
﻿
App({
  onLaunch: function () {
    Push.createNotificationChannel({
          channelID: "",  // ID of the custom channel
          channelName: "",  // Name of the custom channel
          channelDesc: "",  // Description of the custom channel
          channelSound: ""  // Name of the custom ringtone file, without the filename extension
        }).then((ret) => {
          console.info("createNotificationChannel success", ret);
        }).catch((ret) => {
          console.error("createNotificationChannel failed", ret);
        });
    }
})
Note:
An iOS custom ringtone cannot exceed 30 seconds.
WeChat Developer Tools 1.06.2412042 or later is required.
1. Add the custom ringtone file
Add the ringtone file to the project directory, as shown below:
﻿
﻿
﻿
2. Build the app to check whether the ringtone is included in the IPA. The ringtone cannot exceed 30 seconds.
﻿
﻿
﻿
Server-side REST API
Request example
{
  "From_Account": "administrator",
  "To_Account": ["100480"], 
  "MsgRandom": 3674128,
  "OfflinePushInfo": {
      "PushFlag": 0, 
      "Title": "Offline push title 1adad1",
      "Desc": "Offline push content 11adasd1",
      "Ext":"{\"aa\":12123}",
      "AndroidInfo": {
           "Sound": "private_ring123",  // Must match the ringtone filename in the channel created on the client
           "OPPOChannelID": "test_oppo_channel_id",
           "XiaoMiChannelID": "test_xiaomi_channel_id",
           "GoogleChannelID": "test_google_channel_id"
       },
       "ApnsInfo": {
            "Sound": "01.caf"// Must match the ringtone filename in the receiving client's IPA
       }
    }
}
﻿
﻿
Custom Definition Ringtone

Feature overview

Channel support

Platform-specific implementation

Earlier than Android 8.0

Android 8.0 or later

FCM

Receiving client

Configuring a private message channel and custom ringtone (required for OPPO and FCM)

Sending client

1. Upgrade @tencentcloud/chat to the latest version

2. Send a message and configure custom ringtone parameters in offlinePushInfo

Receiving client

Sending client

Client configuration

1. Add the custom ringtone file

﻿﻿﻿

2. Create a client notification channel

1. Add the custom ringtone file

2. Build the app to check whether the ringtone is included in the IPA. The ringtone cannot exceed 30 seconds.

﻿﻿﻿

Server-side REST API

Request example

2. Send a message and configure custom ringtone parameters in `offlinePushInfo`
