Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

Push Notification

Upload certificate to Hyphenate console

In order to implement push notifications, you need to register iOS APNs first. Here's the guide:
Setup APNs.

When Will Hyphenate Server Pushes Notification?

Hyphenate will only send push notifications to the user if the user is offline, which means the user's device is disconnected from the Hyphenate server. This could occur under the following scenarios,

  1. The app is terminated, NOT just in the background
  2. User logs out from the app

Hyphenate will NOT push 'push notifications' if the long connection to the Hyphenate service exists, which could fall under:

  1. User login and app is in the foreground
  2. App is in the background, but the SDK will keep the long connection alive for an extended period of time
- (void)applicationDidEnterBackground:(UIApplication *)application {
    [[EMClient sharedClient] applicationDidEnterBackground:application];

To test the push notification for a terminated app, simply go to your home screen and terminate the app by swiping it out.


1. Initialize push notifications for SDK


EMOptions *options = [EMOptions optionsWithAppkey:@"hyphenatedemo#hyphenatedemo"];    // API key. ex. hyphenatedemo#hyphenatedemo
options.apnsCertName = @"apnsCertName";
[[EMClient sharedClient] initializeSDKWithOptions:options];

2. Register remote notifications


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    [self registerAPNS];

- (void)registerAPNS
    UIApplication *application = [UIApplication sharedApplication];
    application.applicationIconBadgeNumber = 0;

    if (NSClassFromString(@"UNUserNotificationCenter")) {
        [[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert completionHandler:^(BOOL granted, NSError *error) {
            if (granted) {
                [application registerForRemoteNotifications];

    if ([application respondsToSelector:@selector(registerUserNotificationSettings:)])
        UIUserNotificationType notificationTypes = UIUserNotificationTypeBadge | UIUserNotificationTypeSound | UIUserNotificationTypeAlert;
        UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:notificationTypes categories:nil];
        [application registerUserNotificationSettings:settings];

    if ([application respondsToSelector:@selector(registerForRemoteNotifications)]) {
        [application registerForRemoteNotifications];

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
    [[EMClient sharedClient] registerForRemoteNotificationsWithDeviceToken:deviceToken
                                                                completion:^(EMError *aError) {
        if (!aError) {
            // remote notification registration succeed
        else {
            // handle the registration error     

- (void)applicationDidEnterBackground:(UIApplication *)application
    [[EMClient sharedClient] applicationDidEnterBackground:application];
} else {
    UIRemoteNotificationType notificationTypes = UIRemoteNotificationTypeBadge |
    UIRemoteNotificationTypeSound |
    [[UIApplication sharedApplication] registerForRemoteNotificationTypes:notificationTypes];

3. Assign device token to SDK

After successfully registering, pass the deviceToken from delegate method to the Hyphenate SDK.

// pass deviceToken to SDK
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
    [[EMClient sharedClient] bindDeviceToken:deviceToken];

// deviceToken registration failed
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error{
    NSLog(@"error -- %@",error);

4. Disconnect from Chat Service

When logging out of your app, you need to unbind the device token. Call the logout method
[[EMClient sharedClient] logout:YES completion:^(EMError *aError) {}.
In case if you want to conditionally connection/disconnect user from the chat server, but continue to receive the push notification, then you can call the method logout: completion: and passing YES for parameter aIsUnbindDeviceToken.

 *  @param aIsUnbindDeviceToken     Unbind device token to disable the Apple Push Notification Service
 *  @param aCompletionBlock         The callback of completion block
- (void)logout:(BOOL)aIsUnbindDeviceToken
    completion:(void (^)(EMError *aError))aCompletionBlock;

APNs registration failure

  • Typically the error is caused by certification issues or simulators. Please test using a physical iOS device instead of a simulator.

APNs Settings

Get APNs Settings

Get APNs settings from the Hyphenate server

EMError *error = nil;
EMPushOptions *options = [[EMClient sharedClient] getPushOptionsFromServerWithError:&error];

Set APNs Settings

Use the following method to push the APNs settings update to the Hyphenate server. Includes settings in EMPushNotificationOptions, Do Not Disturb settings, Nickname, push notification style.

- (EMError *)updatePushOptionsToServer;
[[EMClient sharedClient] updatePushOptionsToServer];

Push Notification Nicknames and Display Names

Set APNs Nickname and Display Name

Set APNs nickname after successful login

[[EMClient sharedClient] setApnsNickname:@"push nickname"];

Get APNs Nickname and Display Name


@property (nonatomic, copy) NSString *displayName;

Set Push Notification Style

EMPushOptions *options = [[EMClient sharedClient] pushOptions];
options.displayStyle == EMPushDisplayStyleMessageSummary    // display message content
// options.displayStyle == EMPushDisplayStyleSimpleBanner   // display "You have a new message"
EMError *error = [[EMClient sharedClient] updatePushOptionsToServer]; // update APNs setting on server. Sync method. 
if(!error) {
   // registration succeed
}else {
   // registration failed

Do Not Disturb

Set Do Not Disturb setting after successful login

 @brief Do Not Disturb settings
 @constant EMPushNoDisturbStatusDay     All day
 @constant EMPushNoDisturbStatusCustom  Custom time period
 @constant EMPushNoDisturbStatusClose   turn off do not disturb
typedef NS_ENUM(NSInteger, EMPushNoDisturbStatus) {
    EMPushNoDisturbStatusDay = 0,


// Do not disturb all day, will not receive push at all
EMPushOptions *options = [[EMClient sharedClient] pushOptions];
options.noDisturbStatus = EMPushNoDisturbStatusDay;
options.noDisturbingStartH = 0;
options.noDisturbingEndH = 24;
EMError *error = [[EMClient sharedClient] updatePushOptionsToServer];
// will not receive push for specified time period
EMPushOptions *options = [[EMClient sharedClient] pushOptions];
options.noDisturbStatus = EMPushNoDisturbStatusCustom;
options.noDisturbingStartH = 9;
options.noDisturbingEndH = 22;
EMError *error = [[EMClient sharedClient] updatePushOptionsToServer];

Group Push Settings

Enable/Disable Push for Group

- (EMError *)ignoreGroupPush:(NSString *)aGroupId
[[EMClient sharedClient].groupManager ignoreGroupPush:@"groupId" ignore:YES];

Enable/Disable Push for Group(s)

- (EMError *)ignoreGroupsPush:(NSArray *)aGroupIDs
//[[EMClient sharedClient].groupManager ignoreGroupsPush:@[@"group1",@"group2"] ignore:YES];

Get a List of Group Disable Push

NSArray *ignoredGroupIds = [[EMClient sharedClient].groupManager getAllIgnoredGroupIds];

Next Section: Setup APNs

Updated 2 years ago

Push Notification

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.