Last updated: 2023-09-21 15:37:01Download PDF
The offline wake-up function allows your app to receive audio and video call alerts even when it is running in the background or in an offline state. TUICallKit uses Apple's system-level push channel (APNs) for message notifications.

Configure Offline Push

Step 1: Enable App Remote Push

1. Log in to the Apple Developer Center website, and click on Certificates, Identifiers & Profiles or Certificates, IDs & Profiles in the sidebar to enter the Certificates, IDs & Profiles page.

2. Click the + next to Identifiers.

3. You can follow the steps below to create a new AppID, or add a Push Notification Service to your existing AppID.
Please note that the Bundle ID of your App cannot use the wildcard *, otherwise the remote push service cannot be used.
4. Check App IDs, click Continue to proceed.

5. Select App and click Continue to proceed.

6. Configure Bundle ID and other information, then click Continue to proceed.

7. Check Push Notifications to enable the remote push service.

Step 2: Generate Push Certificates

1. Select your AppID, and click Configure.

2. You can see two SSL Certificates in the【Apple Push Notification service SSL Certificates】window, which are used for the remote push certificates of the development environment and production environment, as shown in the picture below:

3. First, select【Create Certificate】for the development environment. The system will prompt us to upload a Certificate Signing Request (CSR).

4. Next, create a CSR file. Open Keychain Access on your Mac, and in the menu, choose Keychain Access - Certificate Assistant - Request a Certificate From a Certificate Authority.

5. Enter your email address, common name (your name or company name), choose Save to disk, click "Continue", and the system will generate a *.certSigningRequest file.

6. Go back to the Apple Developer website in Step3 , click "Choose File" and upload the generated *.certSigningRequest file.

7. Click Continue to generate the push certificate.

8. Click Download to save the Development SSL Certificate locally.

9. Repeat steps 1 to 8 to download the Production SSL Certificate for the production environment.
The production environment certificate is actually a combined certificate of development (Sandbox) and production (Production) environments, which can be used as certificates for both development and production environments.

10. Double-click the downloaded development and production environment SSL Certificates, and the system will import them into the keychain.
11. Open the Keychain app, under Login > My Certificates, right-click on the created VoIP Services certificate.
When saving the P12 file, please be sure to set a password for it.

Step3:Upload certificates to the IM Console

1. Log in to the IM Console.
2. Click on the target application card to enter the application's basic configuration.

3. Click on the Add Certificate button on the right side of iOS Native Offline Push Settings.
4. Choose the certificate type, upload the iOS Certificate (p.12), set the certificate password, and click Confirm.

The uploaded certificate name should preferably be in English (especially without special characters like parentheses).
A password is required when uploading a certificate; without a password, you won't receive push notifications.
For App Store release certificates, set the environment to production, otherwise, you won't receive push notifications.
The uploaded p12 certificate must be a genuine and valid certificate that you applied for.
5. Once the push certificate information is generated, record the certificate ID.


Step4:Complete Project Configuration

To add the required permissions in your application, enable push notification functionality in your Xcode project.
Open your Xcode project, go to Project > Target > Capabilities, click the plus button in the red frame, and select and add Push Notifications. The added result is shown in the yellow frame in the image below:

Step 5: Obtain the deviceToken from Apple every time the App logs in

You can add the following code to your App to request the deviceToken from Apple's backend server:
To ensure compliance, it is recommended to request the deviceToken from Apple only after the user has agreed to the privacy policy.
// Request DeviceToken from Apple's backend
- (void)registerNotification {
[[UIApplication sharedApplication] registerUserNotificationSettings:
[UIUserNotificationSettings settingsForTypes:
(UIUserNotificationTypeSound | UIUserNotificationTypeAlert | UIUserNotificationTypeBadge)
[[UIApplication sharedApplication] registerForRemoteNotifications];

// The deviceToken returned in the AppDelegate's callback needs to be reported to Tencent Cloud backend after login
-(void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
// Record the deviceToken returned by Apple
_deviceToken = deviceToken;

Step 6: Call the API to report it to the IM backend

Once the IM SDK has successfully logged in, you can call the setAPNS API to upload the deviceToken obtained in Step 5 to Tencent Cloud backend. The sample code is as follows:
- (void)pushRegisterIfLogined {
if (self.deviceToken) {
V2TIMAPNSConfig *config = [[V2TIMAPNSConfig alloc] init];
// Users register their Apple developer certificate, download, and generate the certificate (p12 file) from the developer account.
// Pass the generated p12 file to the Tencent Certificate Management Console, and the console will automatically generate a certificate ID.
// Pass the generated certificate ID to the businessID parameter below.
config.businessID = sdkBusiId;
// Value of deviceToken obtained from Apple's backend server
config.token = self.deviceToken;
[[V2TIMManager sharedInstance] setAPNS:config succ:^{
NSLog(@"%s, succ", __func__");
} fail:^(int code, NSString *msg) {
NSLog(@"%s, fail, %d, %@", __func__, code, msg);
// ...

Customize Offline Ringtone

To set the iOSSound field in the offlinePushInfo of the params, please call the call method while dialing and pass the audio file name to iOSSound.
Offline push sound settings (effective for iOS only). If you want to customize iOSSound, you need to link the audio file to the Xcode project first, and then set the audio file name (with extension) to iOSSound.

[[TUICallKit createInstance] call:@"mike's id" params:[self getCallParams] callMediaType:TUICallMediaTypeVideo];

- (TUICallParams *)getCallParams {
    TUIOfflinePushInfo *offlinePushInfo = [self createOfflinePushInfo];
    TUICallParams *callParams = [TUICallParams new];
    callParams.offlinePushInfo = offlinePushInfo;
    callParams.timeout = 30;
    return callParams;

+ (TUIOfflinePushInfo *)createOfflinePushInfo {
    TUIOfflinePushInfo *pushInfo = [TUIOfflinePushInfo new];
    pushInfo.title = @"";
    pushInfo.desc = TUICallingLocalize(@"");
    // iOS push type: if you want user VoIP, please modify type to TUICallIOSOfflinePushTypeVoIP
    pushInfo.iOSPushType = TUICallIOSOfflinePushTypeAPNs;
    pushInfo.ignoreIOSBadge = NO;
    pushInfo.iOSSound = @"phone_ringing.mp3";
    pushInfo.AndroidSound = @"phone_ringing";
    // OPPO must set a ChannelID to receive push messages. This channelID needs to be the same as the console.
    pushInfo.AndroidOPPOChannelID = @"tuikit";
    // FCM channel ID, you need change and set "fcmPushChannelId"
    pushInfo.AndroidFCMChannelID = @"fcm_push_channel";
    // VIVO message type: 0-push message, 1-System message(have a higher delivery rate)
    pushInfo.AndroidVIVOClassification = 1;
    // HuaWei message type:
    pushInfo.AndroidHuaWeiCategory = @"IM";
    return pushInfo;

Frequently Asked Questions

1、Can't receive push notifications and backend reports bad deviceToken error?

The Apple deviceToken is related to the current compilation environment. If the certificate ID used for uploading the deviceToken to Tencent Cloud after logging in to IMSDK and the token are inconsistent, an error will be reported.
If you are using a Release environment for compilation, the - application:didRegisterForRemoteNotificationsWithDeviceToken: callback returns the production environment token. In this case, the businessID needs to be set to the production environment Certificate ID.
If you are using a Debug environment for compilation, the - application:didRegisterForRemoteNotificationsWithDeviceToken: callback returns the development environment token. In this case, the businessID needs to be set to the development environment certificate ID.
V2TIMAPNSConfig *confg = [[V2TIMAPNSConfig alloc] init];
/* Pass the generated p12 file to the Tencent Certificate Management Console, and the console will automatically generate a certificate ID. Pass the generated certificate ID to the busiId parameter below.*
// Push certificate ID
confg.businessID = sdkBusiId;
confg.token = self.deviceToken;
[[V2TIMManager sharedInstance] setAPNS:confg succ:^{

} fail:^(int code, NSString *msg) {


2、Occasionally, iOS development environment does not return deviceToken or prompts APNs to request token failure?

This problem is caused by the instability of APNs service. You can try the following solutions:
1. Insert a SIM card in your phone and test using 4G network.
2. Test after uninstalling and reinstalling the app, restarting the app, or restarting the device.
3. Test with a package under the production environment.
4. Test with other iOS system phones.