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

Basic Operations

Initialize the SDK

  1. Import the SDK header file.
#import <Hyphenate/Hyphenate.h>


Lite version without voice & video calling feature

#import <HyphenateLite/HyphenateLite.h>
  1. Implementation in AppDelegate.m


#import <Hyphenate/EMSDKFull.h>

/** Hyphenate configuration constants **/
static NSString *const kHyphenateAppKey = @"hyphenate#hyphenatedemo";                    // API Key
static NSString *const kHyphenatePushServiceDevelopment = @"DevelopmentCertificate";     // push service certificate name for development
static NSString *const kHyphenatePushServiceProduction = @"ProductionCertificate";       // push service certificate name for production 

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
    EMOptions *options = [EMOptions optionsWithAppkey:kHyphenateAppKey];
    options.apnsCertName = kHyphenatePushServiceProduction;    
    [[EMClient sharedClient] initializeSDKWithOptions:options];

- (void)applicationDidEnterBackground:(UIApplication *)application
    [[EMClient sharedClient] applicationDidEnterBackground:application];

- (void)applicationWillEnterForeground:(UIApplication *)application 
    [[EMClient sharedClient] applicationWillEnterForeground:application];

- (void)registerNotifications
    [self unregisterNotifications];
    [[EMClient sharedClient] addDelegate:self];                  // connection
    [[EMClient sharedClient].chatManager addDelegate:self];      // messaging handling  
    [[EMClient sharedClient].contactManager addDelegate:self];   // contact management  
    [[EMClient sharedClient].groupManager addDelegate:self];     // (optional) group management  
    [[EMClient sharedClient].roomManager addDelegate:self];      // (optional) chat room management  

- (void)unregisterNotifications
    [[EMClient sharedClient] removeDelegate:self];
    [[EMClient sharedClient].chatManager removeDelegate:self];
    [[EMClient sharedClient].contactManager removeDelegate:self];
    [[EMClient sharedClient].groupManager removeDelegate:self];
    [[EMClient sharedClient].roomManager removeDelegate:self];



Here're few init option examples listed in EMOption.h for specific actions,

Enforce HTTPS

If HTTPS is not enforced, then you might encounter an error like App Transport Security has blocked a cleartext HTTP (http://) resource load since it is insecure. Temporary exceptions can be configured via your app's Info.plist file..

@property (nonatomic, assign) BOOL usingHttpsOnly;

Login automatically

@property (nonatomic, assign) BOOL isAutoLogin;

Keep the group message if a user leaves the group?

@property (nonatomic, assign) BOOL isDeleteMessagesWhenExitGroup;

Keep the chat room message if a user leaves the chat room?

@property (nonatomic, assign) BOOL isDeleteMessagesWhenExitChatRoom;


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    EMOptions *options = [EMOptions optionsWithAppkey:@"hyphenatedemo#hyphenatedemo"];
    [options setUsingHttpsOnly:YES];
    [options setIsDeleteMessagesWhenExitGroup: NO];
    [[EMClient sharedClient] initializeSDKWithOptions:options];

Register a New Account

We recommend you register a new Hyphenate account via REST API, but you can also do it from the client SDK.

EMError *error = [[EMClient sharedClient] registerWithUsername:@"apple" password:@"000000"];
if (error==nil) {
    // registered successfully


EMError *error = [[EMClient sharedClient] loginWithUsername:@"username" password:@"password"];
if (!error) {
    // login successfully!

Auto login

Auto login is to log the user into the Hyphenate server automatically without triggering the login method again after a successful login. The attribute of auto login is set to YES by default in the SDK. You can adjust the auto login by changing the setting's successful login.

EMError *error = [[EMClient sharedClient] loginWithUsername:@"username" password:@"password"];
if (!error) {
   // Setting for auto login
   [[EMClient sharedClient].options setIsAutoLogin:YES];   // or NO, to disable auto login

isAutoLogin getter

BOOL isAutoLogin = [EMClient sharedClient].options.isAutoLogin;

Auto login will be canceled under the following situations:

  • The logout method is called and executed from the previous session
  • The user credential or password is changed that causes an auto-login failure
  • The user account is deleted from the server
  • The user logs into another device and the system forces the user to logout on the current device, since it currently only supports login on a single mobile device.

Login Error delegate

- (void) autoLoginDidCompleteWithError:(EMError *)error


@interface someClass() <EMClientDelegate>

- (void)someInitMethod {
    [[EMClient sharedClient] addDelegate:self delegateQueue:nil];

- (void) autoLoginDidCompleteWithError:(EMError *)error {
    // handle auto login error


There are two types of logout scenarios,

Active logout

Active logout is when you call the logout method explicitly.

[[EMClient sharedClient] logout:YES];

Passive logout

Passive logout is triggered if a user is forced to logout by the developer via REST API or console, or exceeded the login session limitation, etc.

User logged into another device and caused a logout on the current device

- (void)userAccountDidLoginFromOtherDevice;

User account is deleted from the server

- (void)userAccountDidRemoveFromServer;

Connection Status Changed

The SDK will attempt to reconnect automatically if the device connection dropped due to a network issue.

- (void) connectionStateDidChange:(EMConnectionState)aConnectionState;
typedef enum {
    EMConnectionConnected = 0,  
} EMConnectionState;

Next step: Messages

Updated 2 years ago

Basic Operations

Suggested Edits are limited on API Reference Pages

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